Shoulda - Making tests easy on the fingers and eyes

Shoulda makes it easy to write elegant, understandable, and maintainable tests. Shoulda consists of matchers, test helpers, and assertions. It’s fully compatible with your existing tests in Test::Unit or RSpec, and requires no retooling to use.

Matchers

Test::Unit- and RSpec-compatible one-liners that test common Rails functionality. These tests would otherwise be much longer, more complex, and error-prone.

Helpers

#context and #should give you RSpec like test blocks in Test::Unit. In addition, you get nested contexts and a much more readable syntax.

Assertions

Many common Rails testing idioms have been distilled into a set of useful assertions.

Usage

ActiveRecord Tests (Shoulda::ActiveRecord::Matchers)

Test your ActiveRecord associations and validations with these powerful matchers:

classPostTest<Test::Unit::TestCaseshouldbelong_to(:user)
shouldhave_many(:tags).through(:taggings)
shouldvalidate_uniqueness_of(:title)
shouldvalidate_presence_of(:body).with_message(/wtf/)
shouldvalidate_presence_of(:title)
shouldvalidate_numericality_of(:user_id)
endclassUserTest<Test::Unit::TestCaseshouldhave_many(:posts)
should_notallow_value("blah").for(:email)
should_notallow_value("b lah").for(:email)
shouldallow_value("a@b.com").for(:email)
shouldallow_value("asdf@asdf.com").for(:email)
shouldensure_inclusion_of(:email).in_range(1..100)
shouldensure_inclusion_of(:age).in_range(1..100)
should_notallow_mass_assignment_of(:password)
end

Makes TDD so much easier.

Controller Tests (Shoulda::Controller::Matchers)

Matchers to test the most common controller patterns…

classPostsControllerTest<ActionController::TestCasecontext"on GET to :show for first record"dosetupdoget:show, :id=>1endshouldassign_to(:user)
shouldrespond_with(:success)
shouldrender_template(:show)
should_notset_the_flashshould"do something else really cool"doassert_equal1, assigns(:user).idendendend

Context Helpers (Shoulda::Context)

Stop killing your fingers with all of those underscores… Name your tests with plain sentences!

classUserTest<Test::Unit::TestCasecontext"A User instance"dosetupdo@user = User.find(:first)
endshould"return its full name"doassert_equal'John Doe', @user.full_nameendcontext"with a profile"dosetupdo@user.profile = Profile.find(:first)
endshould"return true when sent #has_profile?"doassert@user.has_profile?endendendend

Produces the following test methods:

"test: A User instance should return its full name.""test: A User instance with a profile should return true when sent #has_profile?."

So readable!

Helpful Assertions (Shoulda::Assertions)

More to come here, but have fun with what’s there.

assert_same_elements([:a, :b, :c], [:c, :a, :b])
assert_contains(['a', '1'], /\d/)
assert_contains(['a', '1'], 'a')

Rails Installation (Test::Unit)

Specify the gem dependency in your config/environment.rb file:

Rails::Initializer.rundo|config|config.gem"shoulda", :lib=>"shoulda"end

Then:

$ rake gems:install
$ rake gems:unpack

Rails Installation (RSpec)

If you’re using Shoulda with RSpec, we recommend that you add config.gem lines for RSpec and Shoulda in your config/environment/test.rb file, but do not ask Rails to load the RSpec and Shoulda libraries:

config.gem'rspec', :lib=>falseconfig.gem'rspec-rails', :lib=>falseconfig.gem'shoulda', :lib=>false

Then require shoulda from your spec/spec_helper.rb file, before Spec::Runner is configured:

# requires for RSpec
require 'shoulda'
Spec::Runner.configure do |config|
# ...

You should not need to require anything besides the top-level shoulda library.

Rails 3 Installation (RSpec)

With Rails 3 and Bundler, requiring Shoulda is as easy as adding it to your Gemfile:

group:testdogem"shoulda"gem"rspec-rails", "2.0.0.beta.12"end

Shoulda will automatically include matchers into the appropriate example groups.

Credits

Shoulda is maintained and funded by thougthbot

License

Shoulda is Copyright © 2006-2010 Tammer Saleh, Thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.