shoulda-matchers (2.7.0)

Official Documentation

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

ActiveModel Matchers

ActiveRecord Matchers

ActionController Matchers

Independent Matchers

  • delegate_method tests that an object forwards messages to other, internal objects by way of delegation.



Include the gem in your Gemfile:

group :test do
  gem 'shoulda-matchers', require: false

Then require the gem following rspec-rails in your rails_helper (or spec_helper if you're using RSpec 2.x):

require 'rspec/rails'
require 'shoulda/matchers'


shoulda-matchers was originally a component of Shoulda -- it's what provides the nice should syntax which is demonstrated below. For this reason, include it in your Gemfile instead:

group :test do
  gem 'shoulda'

Non-Rails apps

Once it is loaded, shoulda-matchers automatically includes itself into your test framework. It will mix in the appropriate matchers for ActiveRecord, ActiveModel, and ActionController depending on the modules that are available at runtime. For instance, in order to use the ActiveRecord matchers, ActiveRecord must be available beforehand.

If your application is on Rails, everything should "just work", as shoulda-matchers will most likely be declared after Rails in your Gemfile. If your application is on another framework such as Sinatra or Padrino, you may have a different setup, so you will want to ensure that you are requiring shoulda-matchers after the components of Rails you are using. For instance, if you wanted to use and test against ActiveModel, you'd say:

gem 'activemodel'
gem 'shoulda-matchers'

and not:

gem 'shoulda-matchers'
gem 'activemodel'

Generating documentation

YARD is used to generate documentation, which can be viewed online. You can preview changes you make to the documentation locally by running

yard doc

from this directory. Then, open doc/index.html in your browser.

If you want to see a live preview as you work without having to run yard over and over again, keep this command running in a separate terminal session:

watchr docs.watchr


shoulda-matchers follows Semantic Versioning 2.0 as defined at


shoulda-matchers is maintained and funded by thoughtbot. Thank you to all the contributors.


shoulda-matchers is copyright © 2006-2014 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.