Shoulda Matchers

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

Quick links

📖 Read the documentation for the latest version.
📢 See what's changed in recent versions.

Table of contents

• Getting started
  • RSpec
  • Rails apps
  • Non-Rails apps
  • Minitest
    • Rails apps
    • Non-Rails apps
• Usage
  • On the subject of subject
  • Availability of RSpec matchers in example groups
    • Rails projects
    • Non-Rails projects
  • should vs is_expected.to
  • A Note on Testing Style
• Matchers
  • ActiveModel matchers
  • ActiveRecord matchers
  • ActionController matchers
  • Routing matchers
  • Independent matchers
• Extensions
• Contributing
• Compatibility
• Versioning
• Team
• Copyright/License
• About thoughtbot

Getting started

RSpec

Start by including shoulda-matchers in your Gemfile:

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

Then run bundle install.

Now you need to configure the gem by telling it:

• which matchers you want to use in your tests
• that you're using RSpec so that it can make those matchers available in
  your example groups

Rails apps

If you're working on 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

Non-Rails apps

If you're not working on a Rails app, but you still make use of ActiveRecord or
ActiveModel in your project, 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

Minitest

If you're using our umbrella gem Shoulda, then make sure that you're using the
latest version:

group :test do
  gem 'shoulda', '~> 4.0'
end

Otherwise, add shoulda-matchers to your Gemfile:

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

Then run bundle install.

Now you need to configure the gem by telling it:

• which matchers you want to use in your tests
• that you're using Minitest so that it can make those matchers available in
  your test case classes

Rails apps

If you're working on a Rails app, simply place this at the bottom of
test/test_helper.rb:

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

Non-Rails apps

If you're not working on a Rails app, but you still make use of ActiveRecord or
ActiveModel in your project, you can still use this gem too! In that case,
you'll want to place the following configuration at the bottom of
test/test_helper.rb:

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

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

Usage

Most of the matchers provided by this gem are useful in a Rails context, and as
such, can be used for different parts of a Rails app:

• database models backed by ActiveRecord
• non-database models, form objects, etc. backed by
  ActiveModel
• controllers
• routes (RSpec only)
• Rails-specific features like delegate

As the name of the gem indicates, most matchers are designed to be used in
"one-liner" form using the should macro, a special directive available in both
RSpec and Shoulda. For instance, a model test case may look something like:

# RSpec
RSpec.describe MenuItem, type: :model do
  describe 'associations' do
    it { should belong_to(:category).class_name('MenuCategory') }
  end

  describe 'validations' do
    it { should validate_presence_of(:name) }
    it { should validate_uniqueness_of(:name).scoped_to(:category_id) }
  end
end

# Minitest (Shoulda)
class MenuItemTest < ActiveSupport::TestCase
  context 'associations' do
    should belong_to(:category).class_name('MenuCategory')
  end

  context 'validations' do
    should validate_presence_of(:name)
    should validate_uniqueness_of(:name).scoped_to(:category_id)
  end
end

See below for the full set of matchers that you can use.

On the subject of subject

For both RSpec and Shoulda, the subject is an implicit reference to the
object under test, and through the use of should as demonstrated above, all of
the matchers make use of subject internally when they are run. A subject is
always set automatically by your test framework in any given test case; however,
in certain cases it can be advantageous to override it. For instance, when
testing validations in a model, it is customary to provide a valid model instead
of a fresh one:

# RSpec
RSpec.describe Post, type: :model do
  describe 'validations' do
    # Here we're using FactoryBot, but you could use anything
    subject { build(:post) }

    it { should validate_presence_of(:title) }
  end
end

# Minitest (Shoulda)
class PostTest < ActiveSupport::TestCase
  context 'validations' do
    subject { build(:post) }

    should validate_presence_of(:title)
  end
end

When overriding the subject in this manner, then, it's important to provide the
correct object. When in doubt, provide an instance of the class under test.
This is particularly necessary for controller tests, where it is easy to
accidentally write something like:

RSpec.describe PostsController, type: :controller do
  describe 'GET #index' do
    subject { get :index }

    # This may work...
    it { should have_http_status(:success) }
    # ...but this will not!
    it { should permit(:title, :body).for(:post) }
  end
end

In this case, you would want to use before rather than subject:

RSpec.describe PostsController, type: :controller do
  describe 'GET #index' do
    before { get :index }

    # Notice that we have to assert have_http_status on the response here...
    it { expect(response).to have_http_status(:success) }
    # ...but we do not have to provide a subject for render_template
    it { should render_template('index') }
  end
end

Availability of RSpec matchers in example groups

Rails projects

If you're using RSpec, then you're probably familiar with the concept of example
groups. Example groups can be assigned tags to assign different behaviors
to different kinds of example groups. This comes into play especially when using
rspec-rails, where, for instance, controller example groups, tagged with
type: :controller, are written differently than request example groups, tagged
with type: :request. This difference in writing style arises because
rspec-rails mixes different behaviors and methods into controller example
groups vs. request example groups.

Relying on this behavior, Shoulda Matchers automatically makes certain matchers
available in certain kinds of example groups:

• 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 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.

As long as you're using Rails, you don't need to worry about these details —
everything should "just work".

Non-Rails projects

What if you are using ActiveModel or ActiveRecord outside of Rails, however,
and you want to use model matchers in a certain example group? Then you'll
need to manually include the module that holds those matchers into that example
group. For instance, you might have to say:

RSpec.describe MySpecialModel do
  include Shoulda::Matchers::ActiveModel
  include Shoulda::Matchers::ActiveRecord
end

If you have a lot of similar example groups in which you need to do this, then
you might find it more helpful to tag your example groups appropriately, then
instruct RSpec to mix these modules into any example groups that have that tag.
For instance, you could add this to your rails_helper.rb:

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

And from then on, you could say:

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

should vs is_expected.to

In this README and throughout the documentation, you'll notice that we use the
should form of RSpec's one-liner syntax over is_expected.to. Besides being
the namesake of the gem itself, this is our preferred syntax as it's short and
sweet. 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

A Note on Testing Style

If you inspect the source code, you'll notice quickly that shoulda-matchers
is largely implemented using reflections and other introspection methods that
Rails provides. At first sight, this might seem to go against the common
practice of testing behavior rather than implementation. However, as the
available matchers indicate, we recommend that you treat shoulda-matchers as
a tool to help you ensure correct configuration and adherence to best practices
and idiomatic Rails in your models and controllers - especially for aspects
that in your experience are often insufficiently tested, such as ActiveRecord
validations or controller callbacks (a.k.a. the "framework-y" parts).

For testing your application's unique business logic, however, we recommend focusing on
behavior and outcomes over implementation details. This approach will better support
refactoring and ensure that your tests remain resilient to changes in how your code
is structured. While no generalized testing tool can fully capture the nuances of your
specific domain, you can draw inspiration from shoulda-matchers to write custom
matchers that align more closely with your application's needs.

Matchers

Here is the full list of matchers that ship with this gem. If you need details
about any of them, make sure to consult the documentation!

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.
• validate_comparison_of
  tests usage of validates_comparison_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_delegated_type
  tests usage of the delegated_type macro.
• 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_implicit_order_column
  tests usage of implicit_order_column.
• have_many
  tests your has_many associations.
• have_many_attached
  tests your has_many_attached associations.
• have_one
  tests your has_one associations.
• have_one_attached
  tests your has_one_attached associations.
• have_readonly_attribute
  tests usage of the attr_readonly macro.
• have_rich_text
  tests your has_rich_text associations.
• serialize tests
  usage of the serialize macro.
• validate_uniqueness_of
  tests usage of validates_uniqueness_of.
• normalize tests
  usage of the normalize macro
• encrypt
  tests usage of the encrypts macro.

ActionController matchers

• filter_param
  tests parameter filtering configuration.
• permit tests
  that an action restricts 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.

Routing matchers

• route tests
  your routes.

Independent matchers

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

Extensions

Over time our community has created extensions to Shoulda Matchers. If you've
created something that you want to share, please let us know!

• shoulda-matchers-cucumber – Adds support for using Shoulda Matchers in
  Cucumber tests.

Contributing

Have a fix for a problem you've been running into or an idea for a new feature
you think would be useful? Take a look at the Contributing
document for instructions on setting up the repo on your
machine, understanding the codebase, and creating a good pull request.

Compatibility

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

• For Ruby < 2.4 and Rails < 4.1 compatibility, please use v3.1.3.
• For Ruby < 3.0 and Rails < 6.1 compatibility, please use v4.5.1.

Versioning

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

Team

Shoulda Matchers is currently maintained by Pedro Paiva and Matheus
Sales. Previous maintainers include Elliot Winkler,
Gui Albuk, Jason Draper, Melissa Xie,
Gabe Berke-Williams, Ryan McGeary, Joe Ferris, and
Tammer Saleh.

Copyright/License

Shoulda Matchers is copyright © Tammer Saleh and thoughtbot,
inc. It is free and open-source software and may be
redistributed under the terms specified in the LICENSE file.

About thoughtbot

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

We love open source software!
See our other projects.
We are available for hire.