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.
📖 Read the documentation for the latest version.
📢 See what's changed in recent versions.
- Getting started
- Usage
- Matchers
- Extensions
- Contributing
- Compatibility
- Versioning
- Team
- Copyright/License
- About thoughtbot
Start by including shoulda-matchers
in your Gemfile:
group :test do
gem 'shoulda-matchers', '~> 4.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
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
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
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', '~> 4.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
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
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
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.
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
If you're using RSpec, then you're probably familiar with the concept of example
groups. Example groups can be assigned tags order to assign different behavior
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 behavior 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 underspec/models
. - ActionController matchers are available only in controller example groups,
i.e., those tagged with
type: :controller
or in files located underspec/controllers
. - The
route
matcher is available in routing example groups, i.e., those tagged withtype: :routing
or in files located underspec/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".
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
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
. Beside 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
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!
- 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
.
- 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_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
.
- 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.
- route tests your routes.
- delegate_method tests that an object forwards messages to other, internal objects by way of delegation.
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.
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.
Shoulda Matchers is tested and supported against Ruby 2.4 , Rails 4.2 , RSpec 3.x, and Minitest 5.x.
For Ruby < 2.4 and Rails < 4.1 compatibility, please use v3.1.3.
Shoulda Matchers follows Semantic Versioning 2.0 as defined at https://semver.org.
Shoulda Matchers is maintained by Elliot Winkler and Gui Albuk.
Shoulda Matchers is copyright © 2006-2021 Tammer Saleh and thoughtbot, inc. It is free and opensource software and may be redistributed under the terms specified in the LICENSE file.
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.