Module Spec::Rails::Matchers
In: lib/spec/rails/matchers.rb

Spec::Rails::Expectations::Matchers provides several expectation matchers intended to work with Rails components like models and responses. For example:

  response.should redirect_to("some/url") #redirect_to(url) is the matcher.

In addition to those you see below, the arbitrary predicate feature of RSpec makes the following available as well:

  response.should be_success #passes if response.success?
  response.should be_redirect #passes if response.redirect?

Note that many of these matchers are part of a wrapper of assert_select, so the documentation comes straight from that with some slight modifications. assert_select is a Test::Unit extension originally contributed to the Rails community as a plugin by Assaf Arkin and eventually shipped as part of Rails.

For more info on assert_select, see the relevant Rails documentation.


Public Instance methods


  response.should be_valid
  response.should_not be_valid

wrapper for assert_select_rjs

see documentation for assert_select_rjs at

wrapper for assert_select with additional support for using css selectors to set expectation on Strings. Use this in helper specs, for example, to set expectations on the results of helper methods.


  # in a controller spec
  response.should have_tag("div", "some text")

  # in a helper spec (person_address_tag is a method in the helper)
  person_address_tag.should have_tag("input#person_address")

see documentation for assert_select at

Accepts a String or a Regexp, matching a String using == and a Regexp using =~.

If response_or_text has a body, then that is used as to match against else it uses response_or_text

Use this instead of response.should have_tag() when you want to match the whole string or whole body


  response.should have_text("This is the expected text")

Accepts a String, matching using include?

Use this instead of response.should have_text() when you either don’t know or don’t care where on the page this text appears.


  response.should include_text("This text will be in the actual string")

Passes if the response is a redirect to the url, action or controller/action. Useful in controller specs (integration or isolation mode).


  response.should redirect_to("path/to/action")
  response.should redirect_to("")
  response.should redirect_to(:action => 'list')

For use in controller code examples (integration or isolation mode).

Passes if the specified template (view file) is rendered by the response. This file can be any view file, including a partial. However if it is a partial it must be rendered directly i.e. you can’t detect that a partial has been rendered as part of a view using render_template. For that you should use a message expectation (mock) instead:

  controller.should_receive(:render).with(:partial => 'path/to/partial')

template can include the controller path. It can also include an optional extension, which you only need to use when there is ambiguity.

Note that partials must be spelled with the preceding underscore.


  response.should render_template('list')
  response.should render_template('same_controller/list')
  response.should render_template('other_controller/list')

  # with extensions
  response.should render_template('list.rjs')
  response.should render_template('list.haml')
  response.should render_template('same_controller/list.rjs')
  response.should render_template('other_controller/list.rjs')

  # partials
  response.should render_template('_a_partial')
  response.should render_template('same_controller/_a_partial')
  response.should render_template('other_controller/_a_partial')

wrapper for assert_select_email

see documentation for assert_select_email at

wrapper for assert_select_encoded

see documentation for assert_select_encoded at

wrapper for a nested assert_select

  response.should have_tag("div#form") do
    with_tag("input#person_name[name=?]", "person[name]")

see documentation for assert_select at

wrapper for a nested assert_select with false

  response.should have_tag("div#1") do
    without_tag("span", "some text that shouldn't be there")

see documentation for assert_select at