Shoulda Matchers

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

View the documentation for the latest version (4.0.1).

---

• Getting started
  • RSpec
    • Availability of matchers in various example groups
    • should vs is_expected.to
  • Minitest
• Matchers
  • ActiveModel matchers
  • ActiveRecord matchers
  • ActionController matchers
  • Independent matchers
• Compatibility
• Contributing
• Versioning
• License
• About thoughtbot

Getting started

RSpec

Start by including shoulda-matchers in your Gemfile:

group :test do
  gem 'shoulda-matchers'
  gem 'rails-controller-testing'
end

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 providing a configuration block. Where this goes and what this contains depends on your project.

Rails apps

Assuming you are testing a Rails app, simply place this at the bottom of spec/rails_helper.rb (or in a support file if you so choose):

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

Now you're ready to use matchers in your tests! For instance, you might decide to add a matcher to one of your models:

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

Non-Rails apps

If your project isn't a Rails app, but you still make use of ActiveRecord or ActiveModel, you can still use this gem too! In that case, you'll want to place the following configuration at the bottom of spec/spec_helper.rb:

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec

    # Keep as many of these lines as are necessary:
    with.library :active_record
    with.library :active_model
  end
end

Now you're ready to use matchers in your tests! For instance, you might decide to add a matcher to one of your models:

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

For more of an idea of what you can use, see the list of matchers below.

Availability of matchers in various example groups

Regardless of your project, it's important to keep in mind that 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:

require 'shoulda-matchers'

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

Then you can say:

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

should vs is_expected.to

Note that in this README and throughout the documentation we're using the should form of RSpec's one-liner syntax over is_expected.to. 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 is_expected.to, you can do that too:

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

Minitest

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 and 4.x, so you'll want to add the following to your Gemfile:

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

Now you're ready to use matchers in your tests! For instance, you might decide to add a matcher to one of your models:

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

For more of an idea of what you can use, see the list of matchers below.

Matchers

ActiveModel matchers

• allow_value tests that an attribute is valid or invalid if set to one or more values. (Aliased as #allow_values.)
• have_secure_password tests usage of has_secure_password.
• validate_absence_of tests usage of validates_absence_of.
• validate_acceptance_of tests usage of validates_acceptance_of.
• validate_confirmation_of tests usage of validates_confirmation_of.
• validate_exclusion_of tests usage of validates_exclusion_of.
• validate_inclusion_of tests usage of validates_inclusion_of.
• validate_length_of tests usage of validates_length_of.
• validate_numericality_of tests usage of validates_numericality_of.
• validate_presence_of tests usage of validates_presence_of.

ActiveRecord matchers

• accept_nested_attributes_for tests usage of the accepts_nested_attributes_for macro.
• belong_to tests your belongs_to associations.
• define_enum_for tests usage of the enum macro.
• have_and_belong_to_many tests your has_and_belongs_to_many associations.
• have_db_column tests that the table that backs your model has a specific column.
• have_db_index tests that the table that backs your model has an index on a specific column.
• have_many tests your has_many associations.
• have_one tests your has_one associations.
• have_readonly_attribute tests usage of the attr_readonly macro.
• serialize tests usage of the serialize macro.
• validate_uniqueness_of tests usage of validates_uniqueness_of.

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.

Compatibility

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

For Ruby < 2.4 and Rails < 4.1 compatibility, please use v3.1.3.

Contributing

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.

Versioning

Shoulda Matchers follows Semantic Versioning 2.0 as defined at http://semver.org.

License

Shoulda Matchers is copyright © 2006-2019 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.