Simple one-liner tests for common Rails functionality
Go to file
Elliot Winkler e2154f9e4e Simplify Rubocop configuration
The original Rubocop configuration was copied from other thoughtbot
projects. Of course, Rubocop comes with its own set of default settings.
Therefore, we don't need to re-specify settings that it already has --
we only need to specify the ones that we're overriding.

Besides this, Rubocop isn't even in the Gemfile, so even though Hound
runs on GitHub automatically, it'd be nice to spot style issues as you
are editing files.

Given this, this commit simplifies the Rubocop configuration and also
adds Rubocop to the Gemfile so that you can configure your editor to
lint files as you are editing them.
2018-10-04 21:30:01 -03:00
bin Update contributor docs, add maintainer docs 2018-10-02 10:17:20 -03:00
doc_config Fix UI issues with generated docs 2018-10-02 10:13:55 -03:00
docs/errors Update RSpec test style across docs 2016-06-15 18:02:07 -06:00
gemfiles Simplify Rubocop configuration 2018-10-04 21:30:01 -03:00
lib Update gem version to 4.0.0.rc1 2018-10-02 13:34:55 -03:00
script Update util scripts to use Ruby versions in .travis.yml 2018-01-24 00:30:10 -06:00
spec Fix default behavior of belong_to under Rails 4.2 2018-09-16 12:21:41 -06:00
tasks Extend list of files to watch to regen docs 2015-10-08 21:30:42 -06:00
.gitignore Upgrade RSpec to v3.4 2015-12-30 21:58:31 -05:00
.hound.yml Update .rubocop.yml 2017-02-06 22:08:20 +01:00
.python-version Make it possible to run YARD locally 2018-10-02 10:14:26 -03:00
.rubocop.yml Simplify Rubocop configuration 2018-10-04 21:30:01 -03:00
.travis.yml Update supported Ruby and Rails versions 2018-09-13 11:48:42 -03:00
.yardopts Add docs for NonCaseSwappableValueError 2015-10-08 21:30:42 -06:00
Appraisals Update supported Ruby and Rails versions 2018-09-13 11:48:42 -03:00
CONTRIBUTING.md Update contributor docs, add maintainer docs 2018-10-02 10:17:20 -03:00
Gemfile Simplify Rubocop configuration 2018-10-04 21:30:01 -03:00
Gemfile.lock Simplify Rubocop configuration 2018-10-04 21:30:01 -03:00
MAINTAINING.md Update contributor docs, add maintainer docs 2018-10-02 10:17:20 -03:00
MIT-LICENSE Update README.md to 4.0.0.rc1 2018-10-02 13:34:55 -03:00
NEWS.md Update NEWS 2018-09-15 13:43:30 -03:00
README.md Update README.md to 4.0.0.rc1 2018-10-02 13:34:55 -03:00
Rakefile Update CONTRIBUTING 2018-01-24 00:30:10 -06:00
custom_plan.rb Zeus: Wrap Gem::LoadError in more informative error 2016-01-27 20:26:24 -07:00
shoulda-matchers.gemspec Updated homepage in gemspec 2018-09-03 16:15:42 -03:00
zeus.json Fix Zeus so that it runs again on Ruby >= 2.5.x 2018-09-12 21:53:53 -06:00

README.md

Shoulda Matchers Gem Version Build Status Downloads Hound

shoulda-matchers

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.

Documentation

View the official documentation for the latest version (4.0.0.rc1).

Compatibility

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

For Rails 4.0/4.1 and Ruby 2.0/2.1 compatibility, please use shoulda-matchers 3.1.2.

Getting started

RSpec

Start by including shoulda-matchers in your Gemfile:

group :test do
  gem 'shoulda-matchers', '4.0.0.rc1'
  gem 'rails-controller-testing' # If you are using Rails 5.x
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 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

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)
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 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

Matchers

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.

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-2018 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

About thoughtbot

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.