Project: stendhal - The Ruby Toolbox

#stendhal

A small test framework developed as a personal kata to improve my ruby.

Tested with Ruby 1.8.7, 1.9.2, JRuby 1.5.3 and Rubinius 1.1.

Currently under development, there is only basic functionality for now. Below I will be posting whatever features are available throughout the development.

##Current features

Pretty decent reporter with colors
Test doubles and stubs (also partial stubbing!)
Mocks (message expectations) with optionally stubbable return values
Nested example groups (declare them with either describe or context)
Pending examples
A rake task to run the specs
Matchers (use with object.must or object.must_not)

eq() / eql()

be_a() / be_kind_of() / be_a_kind_of()

be_whatever # asks object.whatever?

##Installation

gem install stendhal

##Usage

In your Gemfile:

gem 'stendhal'

If you want the :spec task, in your Rakefile:

require 'stendhal'
Stendhal::RakeTask.new

task :default => :spec

##Syntax

# your spec file for some class - foo_spec.rb

describe "Foo" do

  it "does something" do
    my_object = MyClass.new
    my_object.must be_a(MyClass) 
  end

  
  it "fails when 7 is not 9" do
    (3 + 4).must eq(9)
  end

  it "asks for a kind of object" do
    "string".must be_a(String)
  end

  it "asks things to objects" do
    "string".must be_frozen
  end

  it "has common sense" do
    "string".must_not eq(3)
  end

  describe "Pending examples" do

    it "should do something but I don't know what yet"

    pending "will do something else" do
      my_object = MyClass.new
      my_object.future_method
    end

    context "under some unknown circumstances" do
      it "may act differently" do
        MyClass.must be_a(Class)
      end
    end

  end

  describe "Test double" do
    it "is declared with fake" do
      my_logger = fake('logger')
    end

    it "is declared with double as well" do
      my_logger = double('logger')
    end

    it "can be given stubs" do
      my_logger = double('logger', :my_method => 6)
      my_logger.my_method.must eq(6)
    end
  end

  describe "Partial stubbing" do
    it "returns nil by default" do
      string = "my string"
      string.stubs(:some_method)

      string.some_method # => nil
    end

    it "returns a value if you tell it to" do
      string = "my string"
      string.stubs(:some_method) { 'some value' }

      string.some_method # => "some value"
    end
  end

  describe "Message expectation" do
    it "is declared with expects" do
      string = "my string"
      string.expects(:reverse)

      string.reverse # Expectation fulfilled!
    end

    it "can be told the number of times it is expected" do
      string = "my string"
      string.expects(:reverse).once # or
      string.expects(:reverse).twice # or
      string.expects(:reverse).exactly(3).times

      string.reverse # Fails!
    end

    it "can return a stubbed value" do
      string = "my string"
      string.expects(:reverse).and_returns 'stubbed value'

      string.reverse # => "stubbed value"
    end

    it "can return a stubbed proc" do
      string = "my string"
      string.expects(:reverse).and_returns do
        3 + 4
      end

      string.reverse # => 7
    end

    it "is declared with does_not_expect in case it is negative" do
      string = "my string"
      string.does_not_expect(:reverse)

      string.reverse # Fails!
    end
  end

end

###Running the specs!

stendhal foo_spec.rb

###And the nice colored output...

Foo
  * does something
  * fails when 7 is not 9 [FAILED]
    expected 7 to equal 9
  * asks for a kind of object
  * asks things to objects [FAILED]
    expected "string" to be frozen
  * has common sense

Pending examples
  * should do something but I don't know what yet
  * will do something else
  under some unknown circumstances
    * may act differently

Test double
  * is declared with fake
  * is declared with double as well
  * can be given stubs

Partial stubbing
  * returns nil by default
  * returns a value if you tell it to

Message expectation
  * is declared with expects
  * can be told the number of times it is expected [FAILED]
  * can return a stubbed value
  * can return a stubbed proc
  * is declared with does_not_expect in case it is negative [FAILED]

18 examples, 4 failures, 2 pending

##Feedback

Reporting issues, asking for new features and constructive criticizing can be done either through Github issues, the mailing list (http://librelist.com/browser/stendhal/) or you can always reach me on twitter (I am @txustice). Don't hesitate to tell me anything! :)

##Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add specs for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. If you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull.
Send me a pull request. Bonus points for topic branches.

stendhal

Development

Copyright