Simple one-liner tests for common Rails functionality
Clone or download
mcmire Fix default behavior of belong_to under Rails 4.2
Rails 5 introduced a change where `belongs_to` would default to adding a
presence validation along with the association. However, it also
introduced a configuration option, `belongs_to_required_by_default`, to
emulate the old behavior prior to Rails 5. For Rails 4.2 projects as
well as Rails 5 which were migrated from 4, this setting is false, so
that existing apps do not break.

To mimic this, a change was made to the `belong_to` matcher to check for
the presence of the presence validator if
`belongs_to_required_by_default` is true and check for the absence of
the presence validator if it is false. However, this last bit of the
logic actually causes problems. Take this case, for example:

    ActiveRecord::Base.belongs_to_required_by_default = false

    class Post < ActiveRecord::Base
      belongs_to :user
      validates :user, presence: true

    RSpec.describe Post, type: :model do
      it { belong_to(:user) }

In this example, the developer has chosen to place a presence validation
on the association manually. `belong_to` doesn't know this, however, and
will check to make sure that `user` can be nil, which of course it
can't. Therefore, this test will fail. In addition, the failure message
that `belong_to` generates is confusing:

    Expected Post to have a belongs_to association called user (the
    association should have been defined with `optional: true`, but was

The reason why the test fails is that when
`belongs_to_required_by_default` is false, belong_to` will place an
implicit `optional` qualifier on itself. In other words, these two tests
are equivalent:

    it { belong_to(:user) }
    it { belong_to(:user).optional }

However, this is not only wrong, but the `belongs_to` macro in Rails 4.2
doesn't have an `optional` option (it has `required` instead), so the
failure message that `belong_to` generates is confusing.

This commit fixes this by modifying `belong_to` so that under Rails 4.2,
the matcher will have not have any qualifiers on it by default.
Latest commit a465e79 Sep 12, 2018

Shoulda Matchers Gem Version Build Status Downloads Hound

Shoulda Matchers provides RSpec- and Minitest-compatible one-liners that test common Rails functionality. These tests would otherwise be much longer, more complex, and error-prone.

View the official documentation for the latest version (3.1.1).

This is the master branch

We are currently working on shoulda-matchers 4.0, which will support Ruby 2.4 and Rails 5.x. We don't have a date on when this will be released, but you can stay up to date on the progress by monitoring the milestone. Use this branch at your discretion!

ActiveModel matchers

ActiveRecord matchers

ActionController matchers

  • filter_param tests parameter filtering configuration.
  • permit tests that an action places a restriction on the params hash.
  • redirect_to tests that an action redirects to a certain location.
  • render_template tests that an action renders a template.
  • render_with_layout tests that an action is rendered with a certain layout.
  • rescue_from tests usage of the rescue_from macro.
  • respond_with tests that an action responds with a certain status code.
  • route tests your routes.
  • set_session makes assertions on the session hash.
  • set_flash makes assertions on the flash hash.
  • use_after_action tests that an after_action callback is defined in your controller.
  • use_around_action tests that an around_action callback is defined in your controller.
  • use_before_action tests that a before_action callback is defined in your controller.

Independent matchers

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

Getting started


Start by including shoulda-matchers in your Gemfile:

group :test do
  gem 'shoulda-matchers', '~> 3.1'

We typically use rspec-rails alongside shoulda-matchers, but if for some reason you do not want to do this, and your app is on Rails 5+, you'll want to add the rails-controller-testing gem as well:

group :test do
  gem 'rails-controller-testing'

Now you need to tell the gem a couple of things:

  • Which test framework you're using
  • Which portion of the matchers you want to use

You can supply this information by using a configuration block. Place the following in rails_helper.rb:

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    # Choose a test framework:
    with.test_framework :rspec
    with.test_framework :minitest
    with.test_framework :minitest_4
    with.test_framework :test_unit

    # Choose one or more libraries:
    with.library :active_record
    with.library :active_model
    with.library :action_controller
    # Or, choose the following (which implies all of the above):
    with.library :rails

Now you can use matchers in your tests. For instance, a model test might look like this:

RSpec.describe Person, type: :model do
  it { should validate_presence_of(:name) }

Availability of matchers in various example groups

Since shoulda-matchers provides four categories of matchers, there are four different levels where you can use these matchers:

  • ActiveRecord and ActiveModel matchers are available only in model example groups, i.e., those tagged with type: :model or in files located under spec/models.
  • ActionController matchers are available only in controller example groups, i.e., those tagged with type: :controller or in files located under spec/controllers.
  • The route matcher is available also in routing example groups, i.e., those tagged with type: :routing or in files located under spec/routing.
  • Independent matchers are available in all example groups.

If you are using ActiveModel or ActiveRecord outside of Rails and you want to use model matchers in certain example groups, you'll need to manually include them. Here's a good way of doing that:

RSpec.configure do |config|
  config.include(Shoulda::Matchers::ActiveModel, type: :model)
  config.include(Shoulda::Matchers::ActiveRecord, type: :model)

Then you can say:

describe MySpecialModel, type: :model do
  # ...

should vs

Note that in this README and throughout the documentation we're using the should form of RSpec's one-liner syntax over The should form works regardless of how you've configured RSpec -- meaning you can still use it even when using the expect syntax. But if you prefer to use, you can do that too:

RSpec.describe Person, type: :model do
  it { validate_presence_of(:name) }


Shoulda Matchers was originally a component of Shoulda, a gem that also provides should and context syntax via shoulda-context.

At the moment, shoulda has not been updated to support shoulda-matchers 3.x, so you'll want to add the following to your Gemfile:

group :test do
  gem 'shoulda', '~> 3.5'
  gem 'shoulda-matchers', '~> 2.0'

Now you can use matchers in your tests. For instance a model test might look like this:

class PersonTest < ActiveSupport::TestCase
  should validate_presence_of(:name)

Running tests

Unit tests

Unit tests are the most common kind of tests in this gem, and the best way to run them is by using Zeus.

You'll want to run zeus start in one shell, then in another shell, instead of using rspec to run tests, you can use zeus rspec. So for instance, you might say:

zeus rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb

As a shortcut, you can also drop the initial part of the path and say this instead:

zeus rspec active_model/validate_inclusion_of_matcher_spec.rb

Acceptance tests

The gem uses Appraisal to test against multiple versions of Rails and Ruby. This means that if you're trying to run a single test file, you'll need to specify which appraisal to use. For instance, you can't simply say:

rspec spec/acceptance/active_model_integration_spec.rb

Instead, you need to say

bundle exec appraisal 5.1 rspec spec/acceptance/active_model_integration_spec.rb

All tests

You can run all tests by saying:

bundle exec rake

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 be able to regenerate the docs as you work without having to run yard doc over and over again, keep this command running in a separate terminal session:

rake docs:autogenerate


Shoulda Matchers is open source, and we are grateful for everyone who's contributed so far.

If you'd like to contribute, please take a look at the instructions for installing dependencies and crafting a good pull request.


Shoulda Matchers is tested and supported against Rails 5.x, Rails 4.2+, RSpec 3.x, Minitest 5, Minitest 4, and Ruby 2.2+.


Shoulda Matchers follows Semantic Versioning 2.0 as defined at


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

About thoughtbot


Shoulda Matchers is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We are passionate about open source software. See our other projects. We are available for hire.