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).
Are you a fan of Shoulda Matchers? Are you interested in maintaining a popular open-source project? If so, please contact me. Don't misunderstand me -- I still use Shoulda Matchers on every project, but unfortunately, it has been a long while since I've been able to give it the love it deserves, and I'd like to hand the reins over to someone else who is able to do that. If you're interested, I can be reached on Twitter as @mcmire or at [email protected]. Thanks!
-- Elliot
- allow_mass_assignment_of
tests usage of Rails 3's
attr_accessible
andattr_protected
macros. - 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_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
.
- 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. (Aliased as #use_after_filter.) - use_around_action
tests that an
around_action
callback is defined in your controller. (Aliased as #use_around_filter.) - use_before_action
tests that a
before_action
callback is defined in your controller. (Aliased as #use_before_filter.)
- delegate_method tests that an object forwards messages to other, internal objects by way of delegation.
Include shoulda-matchers
in your Gemfile:
For Rails 4.x:
group :test do
gem 'shoulda-matchers', '~> 3.1'
end
For Rails 5.0:
group :test do
gem 'shoulda-matchers', git: 'https://github.com/thoughtbot/shoulda-matchers.git', branch: 'rails-5'
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 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
end
end
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) }
end
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 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 also in routing example groups, i.e., those tagged withtype: :routing
or in files located underspec/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)
end
Then you can say:
describe MySpecialModel, type: :model do
# ...
end
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
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'
end
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)
end
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
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 4.2 rspec spec/acceptance/active_model_integration_spec.rb
You can run all tests by saying:
bundle exec rake
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 4.x, RSpec 3.x, Minitest 5, Minitest 4, and Ruby 2.x.
Shoulda Matchers follows Semantic Versioning 2.0 as defined at https://semver.org.
Shoulda Matchers is copyright © 2006-2016 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
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.