# shoulda-2.11.0 Documentation

Shoulda makes it easy to write elegant, understandable, and maintainable tests. Shoulda consists of test macros, assertions, and helpers added on to the Test::Unit framework. It's fully compatible with your existing tests, and requires no retooling to use.

Helpers | context and should give you RSpec like test blocks. In addition, you get nested contexts and a much more readable syntax.
Macros | Generate hundreds of lines of Controller and ActiveRecord tests with these powerful macros. They get you started quickly, and can help you ensure that your application is conforming to best practices.
Assertions | Many common rails testing idioms have been distilled into a set of useful assertions.
Matchers | Rspec-compatible matchers providing the same tests as Shoulda macros.

# Usage

### Context Helpers (Shoulda::Context)

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

    class UserTest < Test::Unit::TestCase
      context "A User instance" do
        setup do
          @user = User.find(:first)
        end

        should "return its full name" do
          assert_equal 'John Doe', @user.full_name
        end

        context "with a profile" do
          setup do
            @user.profile = Profile.find(:first)
          end

          should "return true when sent #has_profile?" do
            assert @user.has_profile?
          end
        end
      end
    end

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!

### ActiveRecord Tests (Shoulda::ActiveRecord::Macros)

Quick macro tests for your ActiveRecord associations and validations:

    class PostTest < Test::Unit::TestCase
      fixtures :all

      should_belong_to :user
      should_have_many :tags, :through => :taggings

      should_validate_uniqueness_of :title
      should_validate_presence_of :body, :message => /wtf/
      should_validate_presence_of :title
      should_validate_numericality_of :user_id
    end

    class UserTest < Test::Unit::TestCase
      should_have_many :posts

      should_not_allow_values_for :email, "blah", "b lah"
      should_allow_values_for :email, "a@b.com", "asdf@asdf.com"
      should_ensure_length_in_range :email, 1..100
      should_ensure_value_in_range :age, 1..100
      should_not_allow_mass_assignment_of :password
    end

Makes TDD so much easier.

### Controller Tests (Shoulda::Controller::Macros)

Macros to test the most common controller patterns…

    class PostsControllerTest < ActionController::TestCase
      context "on GET to :show for first record" do
        setup do
          get :show, :id => 1
        end

        should_assign_to :user
        should_respond_with :success
        should_render_template :show
        should_not_set_the_flash

        should "do something else really cool" do
          assert_equal 1, assigns(:user).id
        end
      end
    end

### 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')

### 3rd Party and Application Specific Macros

Any *.rb file under RAILS_ROOT/test/shoulda_macros/ or vendor/(plugins|gems)/gem_name/shoulda_macros/ will be automatically required when you run your tests. This allows you to distribute macros with your plugins, or to organize the macros inside your application. Remember to add your macro to Test::Unit::TestCase in the macro file:

    # test/shoulda_macros/security.rb
    class Test::Unit::TestCase
      def self.should_be_denied(opts = {})
        should_set_the_flash_to(opts[:flash] || /Please log in/i)
        should_redirect_to(opts[:redirect]   || 'login_url')
      end
    end

# Rails Installation (Test::Unit)

### As a Gem

Use this if you prefer to use versioned releases of shoulda. Specify the gem dependency in your config/environment.rb file:

    Rails::Initializer.run do |config|
      config.gem "thoughtbot-shoulda", :lib => "shoulda", :source => "http://gems.github.com"
    end

Then:

    $ rake gems:install
    $ rake gems:unpack

### As a Plugin

Use this if you prefer to use the edge version of shoulda:

    $ script/plugin install git://github.com/thoughtbot/shoulda.git

### As a Plugin (using git submodules)

Use this if you prefer the idea of being able to easily switch between using edge or a tagged version of shoulda:

    $ git submodule add git://github.com/thoughtbot/shoulda.git vendor/plugins/shoulda

# 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 => false
    config.gem 'rspec-rails', :lib => false
    config.gem 'thoughtbot-shoulda',
               :lib => false,
               :source => 'http://gems.github.com'

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.

# Credits

Shoulda is maintained by Tammer Saleh, and is funded by Thoughtbot, inc.

# License

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

## Files

- CONTRIBUTION_GUIDELINES.rdoc
- README.rdoc

## Classes/Modules

- Shoulda
- Shoulda::ActionController
- Shoulda::ActionController::Macros
- Shoulda::ActionController::Matchers
- Shoulda::ActionMailer
- Shoulda::ActionMailer::Assertions
- Shoulda::ActionMailer::Matchers
- Shoulda::ActiveRecord
- Shoulda::ActiveRecord::Assertions
- Shoulda::ActiveRecord::Helpers
- Shoulda::ActiveRecord::Macros
- Shoulda::ActiveRecord::Matchers
- Shoulda::Assertions
- Shoulda::ClassMethods
- Shoulda::Helpers
- Shoulda::InstanceMethods
- Shoulda::Macros
- ActionController
- Test

## Methods

- #allow_mass_assignment_of — Shoulda::ActiveRecord::Matchers
- #allow_value — Shoulda::ActiveRecord::Matchers
- #assert_accepts — Shoulda::Assertions
- #assert_bad_value — Shoulda::ActiveRecord::Assertions
- #assert_contains — Shoulda::Assertions
- #assert_did_not_send_email — Shoulda::ActionMailer::Assertions
- #assert_does_not_contain — Shoulda::Assertions
- #assert_good_value — Shoulda::ActiveRecord::Assertions
- #assert_rejects — Shoulda::Assertions
- #assert_same_elements — Shoulda::Assertions
- #assert_save — Shoulda::ActiveRecord::Assertions
- #assert_sent_email — Shoulda::ActionMailer::Assertions
- #assert_valid — Shoulda::ActiveRecord::Assertions
- #assign_to — Shoulda::ActionController::Matchers
- #before_should — Shoulda::ClassMethods
- #belong_to — Shoulda::ActiveRecord::Matchers
- #context — Shoulda::ClassMethods
- #default_error_message — Shoulda::ActiveRecord::Helpers
- #described_type — Shoulda::ClassMethods
- #ensure_inclusion_of — Shoulda::ActiveRecord::Matchers
- #ensure_length_of — Shoulda::ActiveRecord::Matchers
- #filter_param — Shoulda::ActionController::Matchers
- #have_and_belong_to_many — Shoulda::ActiveRecord::Matchers
- #have_db_column — Shoulda::ActiveRecord::Matchers
- #have_db_index — Shoulda::ActiveRecord::Matchers
- #have_many — Shoulda::ActiveRecord::Matchers
- #have_one — Shoulda::ActiveRecord::Matchers
- #have_readonly_attribute — Shoulda::ActiveRecord::Matchers
- #have_sent_email — Shoulda::ActionMailer::Matchers
- #redirect_to — Shoulda::ActionController::Matchers
- #render_template — Shoulda::ActionController::Matchers
- #render_with_layout — Shoulda::ActionController::Matchers
- #report! — Shoulda::Helpers
- #respond_with — Shoulda::ActionController::Matchers
- #respond_with_content_type — Shoulda::ActionController::Matchers
- #route — Shoulda::ActionController::Matchers
- #set_session — Shoulda::ActionController::Matchers
- #set_the_flash — Shoulda::ActionController::Matchers
- #should — Shoulda::ClassMethods
- #should_allow_mass_assignment_of — Shoulda::ActiveRecord::Macros
- #should_allow_values_for — Shoulda::ActiveRecord::Macros
- #should_assign_to — Shoulda::ActionController::Macros
- #should_belong_to — Shoulda::ActiveRecord::Macros
- #should_change — Shoulda::Macros
- #should_create — Shoulda::Macros
- #should_destroy — Shoulda::Macros
- #should_ensure_length_at_least — Shoulda::ActiveRecord::Macros
- #should_ensure_length_in_range — Shoulda::ActiveRecord::Macros
- #should_ensure_length_is — Shoulda::ActiveRecord::Macros
- #should_ensure_value_in_range — Shoulda::ActiveRecord::Macros
- #should_eventually — Shoulda::ClassMethods
- #should_filter_params — Shoulda::ActionController::Macros
- #should_have_and_belong_to_many — Shoulda::ActiveRecord::Macros
- #should_have_class_methods — Shoulda::ActiveRecord::Macros
- #should_have_db_column — Shoulda::ActiveRecord::Macros
- #should_have_db_columns — Shoulda::ActiveRecord::Macros
- #should_have_db_index — Shoulda::ActiveRecord::Macros
- #should_have_db_indices — Shoulda::ActiveRecord::Macros
- #should_have_instance_methods — Shoulda::ActiveRecord::Macros
- #should_have_many — Shoulda::ActiveRecord::Macros
- #should_have_one — Shoulda::ActiveRecord::Macros
- #should_have_readonly_attributes — Shoulda::ActiveRecord::Macros
- #should_not — Shoulda::ClassMethods
- #should_not_allow_mass_assignment_of — Shoulda::ActiveRecord::Macros
- #should_not_allow_values_for — Shoulda::ActiveRecord::Macros
- #should_not_assign_to — Shoulda::ActionController::Macros
- #should_not_change — Shoulda::Macros
- #should_not_set_the_flash — Shoulda::ActionController::Macros
- #should_redirect_to — Shoulda::ActionController::Macros
- #should_render_template — Shoulda::ActionController::Macros
- #should_render_with_layout — Shoulda::ActionController::Macros
- #should_render_without_layout — Shoulda::ActionController::Macros
- #should_respond_with — Shoulda::ActionController::Macros
- #should_respond_with_content_type — Shoulda::ActionController::Macros
- #should_route — Shoulda::ActionController::Macros
- #should_set_session — Shoulda::ActionController::Macros
- #should_set_the_flash_to — Shoulda::ActionController::Macros
- #should_validate_acceptance_of — Shoulda::ActiveRecord::Macros
- #should_validate_numericality_of — Shoulda::ActiveRecord::Macros
- #should_validate_presence_of — Shoulda::ActiveRecord::Macros
- #should_validate_uniqueness_of — Shoulda::ActiveRecord::Macros
- #subject — Shoulda::InstanceMethods
- #subject — Shoulda::ClassMethods
- #validate_acceptance_of — Shoulda::ActiveRecord::Matchers
- #validate_format_of — Shoulda::ActiveRecord::Matchers
- #validate_numericality_of — Shoulda::ActiveRecord::Matchers
- #validate_presence_of — Shoulda::ActiveRecord::Matchers
- #validate_uniqueness_of — Shoulda::ActiveRecord::Matchers

[Validate]

Generated with the Darkfish Rdoc Generator 2.