Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Collection of testing matchers extracted from Shoulda
branch: master

Permit matcher now supports subparameters

Previously we were taking ActionController::Parameters and completely
overriding #require, forcing it to return `self`, i.e, the entire
ActionController::Parameters object. This meant that we broke its
functionality, which is to return a slice of the params hash instead.
The consequence of this is that attempting to call #permit on a slice of
the params hash obtained via #require would not work:

``` ruby
params =
  { "course" => { "foo" => "bar" } }

This commit fixes the permit matcher so that #require is proxied
instead, retaining the existing behavior.

This commit also adds a qualifier, #on, for asserting that your action
places a restriction on a slice of the params hash. The `permit` matcher
will properly track calls on child `params` instances. For example:

``` ruby
class UsersController < ActionController::Base
  def create


  def user_params
    params.require(:user).permit(:name, :age)

describe UsersController do
  it { should permit(:name, :age).for(:create).on(:user) }

If this fails, you'll get the following error message:

Expected POST #create to restrict parameters for :user to :name and :age,
but restricted parameters were :first_name and :last_name.
latest commit b33f5de55a
Elliot Winkler mcmire authored

shoulda-matchers Gem Version Build Status Downloads

Official Documentation

shoulda-matchers provides Test::Unit- and RSpec-compatible one-liners that test common Rails functionality. These tests would otherwise be much longer, more complex, and error-prone.

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 a after_action callback is defined in your controller. (Aliased as use_after_filter.)
  • use_around_action tests that a 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.)

Independent Matchers

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



Include the gem in your Gemfile:

group :test do
  gem 'shoulda-matchers', require: false

Then require the gem following rspec-rails in your rails_helper (or spec_helper if you're using RSpec 2.x):

require 'rspec/rails'
require 'shoulda/matchers'


shoulda-matchers was originally a component of Shoulda, a meta-gem that also provides should and context syntax via shoulda-context. For this reason you'll want to include this gem in your Gemfile instead:

group :test do
  gem 'shoulda'

Non-Rails apps

Once it is loaded, shoulda-matchers automatically includes itself into your test framework. It will mix in the appropriate matchers for ActiveRecord, ActiveModel, and ActionController depending on the modules that are available at runtime. For instance, in order to use the ActiveRecord matchers, ActiveRecord must be present beforehand.

If your application is written against Rails, everything should "just work", as shoulda-matchers will most likely be declared after Rails in your Gemfile. If your application is written against another framework such as Sinatra or Padrino, you may have a different setup, so you will want to ensure that you are requiring shoulda-matchers after the components of Rails you are using. For instance, if you wanted to use and test against ActiveModel, you'd say:

gem 'activemodel'
gem 'shoulda-matchers'

and not:

gem 'shoulda-matchers'
gem 'activemodel'

Generating documentation

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 see a live preview as you work without having to run yard over and over again, keep this command running in a separate terminal session:

watchr docs.watchr


shoulda-matchers follows Semantic Versioning 2.0 as defined at


shoulda-matchers is maintained and funded by thoughtbot. Thank you to all the contributors.


shoulda-matchers is copyright © 2006-2014 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

Something went wrong with that request. Please try again.