Shoulda

Shoulda is a Ruby testing framework. It has two main purposes:

add context & should blocks to Test::Unit
provide a set of macros for testing Rails apps, no matter what other testing tools you use ( RSpec, context, etc.)

It is written by thoughtbot, the authors of Shoulda (testing framework), Factory Girl (test data for Ruby test suites), and Paperclip (file uploads).

Installation

$ sudo gem install thoughtbot-shoulda -s http://gems.github.com

require 'rubygems' 
gem 'thoughtbot-shoulda' 
require 'shoulda'

Documentation

Shoulda is completely RDoc'd and available online.

should blocks

If you are using Test::Unit, Shoulda provides a sugary should block to replace your test_ methods:

class CalculatorTest < Test::Unit::TestCase 
  should "add two numbers for the sum" do 
    calculator = Calculator.new 
    assert_equal 4, calculator.sum(2, 2)
  end 
end

This style also improves your test's failure messages:

Failure: 
test: Calculator should add two numbers for the sum. 
(CalculatorTest)

context blocks

Shoulda also provides an elegant way to keep your tests well organized & DRY: context blocks.

class CalculatorTest < Test::Unit::TestCase 
  context "a calculator" do 
    setup do 
      @calculator = Calculator.new 
    end 
 
    should "add two numbers for the sum" do 
      assert_equal 4, @calculator.sum(2, 2) 
    end  
 
    should "multiply two numbers for the product" do 
      assert_equal 10, @calculator.product(2, 5) 
    end  
  end 
end

context blocks allow you to create a common setup for multiple should blocks. In the above example, a new Calculator will be instantiated for the two tests:

test: a calculator should add two numbers for the sum. 
test: a calculator should multiply two numbers for the product.

ActiveRecord Macros

Shoulda provides macros to test your Rails app.

Here's an example of testing the validations and associations of a User ActiveRecord model:

class UserTest < Test::Unit::TestCase
  should_validate_presence_of :name, :phone_number
  should_not_allow_values_for :phone_number, "abcd", "1234"
  should_allow_values_for :phone_number, "(123) 456-7890"
 
  should_not_allow_mass_assignment_of :password
 
  should_have_one :profile
  should_have_many :dogs
  should_have_many :messes, :through => :dogs
  should_belong_to :lover
end

For all of these macros, the last parameter may be a hash of options.

For the full list, see the ActionRecord::Macros documentation.

ActiveRecord Matchers

Under the hood, Shoulda's macros use matchers.

As of Shoulda 2.0.7, Shoulda's ActiveRecord matchers are compatible with RSpec, and have no dependencies other than Ruby:

describe User do
  it { should validate_presence_of(:name) }
  it { should validate_presence_of(:phone_number) }
  %w(abcd 1234).each do |value|
    it { should_not allow_value(value).for(:phone_number) }
  end
  it { should allow_value("(123) 456-7890").for(:phone_number) }
  it { should_not allow_mass_assignment_of(:password) }
  it { should have_one(:profile) }
  it { should have_many(:dogs) }
  it { should have_many(:messes).through(:dogs) }
  it { should belong_to(:lover) }
end

The Shoulda core team is working on converting Shoulda's ActionController macros to also be compatible with RSpec.

ActionController macros

Shoulda provides many helpful macros for testing your controllers, too. Below is an example of testing a typical, RESTful show action:

context "on GET to :show for first record" do
  setup do
    @user = Factory(:email_confirmed_user)
    get :show, :id => @user.id
  end
 
  should_assign_to       :user, :equals => "@user"
  should_respond_with    :success
  should_render_template :show
  should_not_set_the_flash
end

Note: “Factory” is provided by Factory Girl and ”:email_confirmed_user” is provided by Clearance.

For the full list, see the ActionController::Macros documentation.