Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

236 lines (185 sloc) 9.509 kb

Shoulda Matchers Gem Version Build Status Downloads

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 (2.8.0).

Heads up! This is the README for the master branch. You might be more interested in the README for 2.8.0 instead.


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.

Installation

RSpec

Include shoulda-matchers in your Gemfile:

group :test do
  gem 'shoulda-matchers'
end

Then, configure the gem to integrate with RSpec.

Now you can use matchers in your tests. For instance a model test might look like this:

describe Person do
  it { should validate_presence_of(:name) }
end

Minitest / Test::Unit

Shoulda Matchers was originally a component of Shoulda, a 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'
end

Then, configure the gem to integrate with Minitest.

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

Configuration

NOTE: The new configuration syntax isn't available in a public release just yet -- please refer to the README for 2.8.0 for the current installation instructions.

Before you can use Shoulda Matchers, you'll need to tell it 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 your test or spec helper:

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 a library:
    with.library :active_record
    with.library :active_model
    with.library :action_controller
    # Or, choose all of the above:
    with.library :rails
  end
end

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:

bundle exec guard

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-2015 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.

Jump to Line
Something went wrong with that request. Please try again.