2015-04-02 10:33:15 -04:00
# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge]
2012-03-09 11:57:31 -05:00
2017-07-07 11:51:26 -04:00
[![Join the chat at https://gitter.im/shoulda-matchers/Lobby ](https://badges.gitter.im/shoulda-matchers/Lobby.svg )](https://gitter.im/shoulda-matchers/Lobby?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
2015-04-02 10:33:15 -04:00
Shoulda Matchers provides RSpec- and Minitest-compatible one-liners that test
2013-10-23 15:27:08 -04:00
common Rails functionality. These tests would otherwise be much longer, more
complex, and error-prone.
2012-03-09 11:57:31 -05:00
2016-01-27 06:23:47 -05:00
[View the official documentation for the latest version (3.1.1).][rubydocs]
2015-04-21 11:43:28 -04:00
----
2015-03-08 10:24:52 -04:00
2017-01-14 18:07:50 -05:00
### Note from the maintainer
> 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
> <elliot.winkler@gmail.com>. Thanks!
>
> -- Elliot
----
2015-04-02 10:33:15 -04:00
### ActiveModel matchers
2014-01-23 13:07:36 -05:00
2014-06-21 19:28:47 -04:00
* **[allow_mass_assignment_of](lib/shoulda/matchers/active_model/allow_mass_assignment_of_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests usage of Rails 3's `attr_accessible` and `attr_protected` macros.
2014-11-18 08:12:20 -05:00
* **[allow_value](lib/shoulda/matchers/active_model/allow_value_matcher.rb)**
2015-09-30 14:51:01 -04:00
tests that an attribute is valid or invalid if set to one or more values.
*(Aliased as #allow_values.)*
2014-11-18 08:12:20 -05:00
* **[have_secure_password](lib/shoulda/matchers/active_model/have_secure_password_matcher.rb)**
tests usage of `has_secure_password` .
2015-05-18 20:13:31 -04:00
* **[validate_absence_of](lib/shoulda/matchers/active_model/validate_absence_of_matcher.rb)**
tests usage of `validates_absence_of` .
* **[validate_acceptance_of](lib/shoulda/matchers/active_model/validate_acceptance_of_matcher.rb)**
tests usage of `validates_acceptance_of` .
2014-06-21 19:28:47 -04:00
* **[validate_confirmation_of](lib/shoulda/matchers/active_model/validate_confirmation_of_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests usage of `validates_confirmation_of` .
2014-11-18 08:12:20 -05:00
* **[validate_exclusion_of](lib/shoulda/matchers/active_model/validate_exclusion_of_matcher.rb)**
tests usage of `validates_exclusion_of` .
* **[validate_inclusion_of](lib/shoulda/matchers/active_model/validate_inclusion_of_matcher.rb)**
tests usage of `validates_inclusion_of` .
* **[validate_length_of](lib/shoulda/matchers/active_model/validate_length_of_matcher.rb)**
tests usage of `validates_length_of` .
2014-06-21 19:28:47 -04:00
* **[validate_numericality_of](lib/shoulda/matchers/active_model/validate_numericality_of_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests usage of `validates_numericality_of` .
2014-11-18 08:12:20 -05:00
* **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
tests usage of `validates_presence_of` .
2014-01-23 13:07:36 -05:00
2015-04-02 10:33:15 -04:00
### ActiveRecord matchers
2014-01-23 13:07:36 -05:00
2014-06-21 19:28:47 -04:00
* **[accept_nested_attributes_for](lib/shoulda/matchers/active_record/accept_nested_attributes_for_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests usage of the `accepts_nested_attributes_for` macro.
2014-11-18 08:12:20 -05:00
* **[belong_to](lib/shoulda/matchers/active_record/association_matcher.rb)**
tests your `belongs_to` associations.
2014-08-28 12:55:52 -04:00
* **[define_enum_for](lib/shoulda/matchers/active_record/define_enum_for_matcher.rb)**
tests usage of the `enum` macro.
2014-06-21 19:28:47 -04:00
* **[have_and_belong_to_many](lib/shoulda/matchers/active_record/association_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests your `has_and_belongs_to_many` associations.
2014-11-18 08:12:20 -05:00
* **[have_db_column](lib/shoulda/matchers/active_record/have_db_column_matcher.rb)**
tests that the table that backs your model has a specific column.
* **[have_db_index](lib/shoulda/matchers/active_record/have_db_index_matcher.rb)**
tests that the table that backs your model has an index on a specific column.
* **[have_many](lib/shoulda/matchers/active_record/association_matcher.rb)**
tests your `has_many` associations.
* **[have_one](lib/shoulda/matchers/active_record/association_matcher.rb)**
tests your `has_one` associations.
2014-06-21 19:28:47 -04:00
* **[have_readonly_attribute](lib/shoulda/matchers/active_record/have_readonly_attribute_matcher.rb)**
2014-01-23 13:07:36 -05:00
tests usage of the `attr_readonly` macro.
2014-11-18 08:12:20 -05:00
* **[serialize](lib/shoulda/matchers/active_record/serialize_matcher.rb)** tests
usage of the `serialize` macro.
2014-12-08 13:15:46 -05:00
* **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
tests usage of `validates_uniqueness_of` .
2014-01-23 13:07:36 -05:00
2015-04-02 10:33:15 -04:00
### ActionController matchers
2014-01-23 13:07:36 -05:00
2014-11-18 08:12:20 -05:00
* **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
tests parameter filtering configuration.
2015-02-28 21:32:09 -05:00
* **[permit](lib/shoulda/matchers/action_controller/permit_matcher.rb)** tests
that an action places a restriction on the `params` hash.
2014-11-18 08:12:20 -05:00
* **[redirect_to](lib/shoulda/matchers/action_controller/redirect_to_matcher.rb)**
tests that an action redirects to a certain location.
* **[render_template](lib/shoulda/matchers/action_controller/render_template_matcher.rb)**
tests that an action renders a template.
* **[render_with_layout](lib/shoulda/matchers/action_controller/render_with_layout_matcher.rb)**
tests that an action is rendered with a certain layout.
* **[rescue_from](lib/shoulda/matchers/action_controller/rescue_from_matcher.rb)**
tests usage of the `rescue_from` macro.
* **[respond_with](lib/shoulda/matchers/action_controller/respond_with_matcher.rb)**
tests that an action responds with a certain status code.
* **[route](lib/shoulda/matchers/action_controller/route_matcher.rb)** tests
your routes.
* **[set_session](lib/shoulda/matchers/action_controller/set_session_matcher.rb)**
makes assertions on the `session` hash.
2014-12-04 02:28:01 -05:00
* **[set_flash](lib/shoulda/matchers/action_controller/set_flash_matcher.rb)**
2014-11-18 08:12:20 -05:00
makes assertions on the `flash` hash.
2015-03-26 16:46:03 -04:00
* **[use_after_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L79)**
2015-09-30 15:25:10 -04:00
tests that an `after_action` callback is defined in your controller. *(Aliased
as #use_after_filter .)*
2015-03-26 16:46:03 -04:00
* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L129)**
2015-09-30 15:25:10 -04:00
tests that an `around_action` callback is defined in your controller. *(Aliased
as #use_around_filter .)*
2015-03-26 16:46:03 -04:00
* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L54)**
2015-09-30 15:25:10 -04:00
tests that a `before_action` callback is defined in your controller. *(Aliased
as #use_before_filter .)*
2014-01-23 13:07:36 -05:00
2015-04-02 10:33:15 -04:00
### Independent matchers
2014-07-18 20:05:22 -04:00
2014-10-02 17:58:20 -04:00
* **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
2014-07-18 20:05:22 -04:00
tests that an object forwards messages to other, internal objects by way of
delegation.
2015-11-05 17:49:04 -05:00
## Getting started
2013-10-23 15:27:08 -04:00
2014-01-10 20:36:52 -05:00
### RSpec
2015-04-02 10:33:15 -04:00
Include `shoulda-matchers` in your Gemfile:
2013-10-23 15:27:08 -04:00
2017-04-24 12:36:08 -04:00
For Rails 4.x:
2014-06-19 23:50:37 -04:00
``` ruby
2013-10-23 15:27:08 -04:00
group :test do
2016-01-27 06:23:47 -05:00
gem 'shoulda-matchers', '~> 3.1'
2013-10-23 15:27:08 -04:00
end
```
2012-03-09 11:57:31 -05:00
2017-04-24 12:36:08 -04:00
For Rails 5.0:
``` ruby
group :test do
gem 'shoulda-matchers', git: 'https://github.com/thoughtbot/shoulda-matchers.git', branch: 'rails-5'
end
```
2016-01-15 13:05:23 -05:00
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` :
``` ruby
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
```
2015-04-02 10:33:15 -04:00
Now you can use matchers in your tests. For instance a model test might look
like this:
2014-04-16 02:47:52 -04:00
2014-06-19 23:50:37 -04:00
``` ruby
2015-11-06 09:48:04 -05:00
RSpec.describe Person, type: :model do
2015-04-02 10:33:15 -04:00
it { should validate_presence_of(:name) }
end
2014-04-16 02:47:52 -04:00
```
2015-11-05 17:49:04 -05:00
#### 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,
2016-01-04 13:29:14 -05:00
i.e., those tagged with `type: :controller` or in files located under
`spec/controllers` .
2015-11-05 17:49:04 -05:00
* 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:
``` ruby
RSpec.configure do |config|
config.include(Shoulda::Matchers::ActiveModel, type: :model)
config.include(Shoulda::Matchers::ActiveRecord, type: :model)
end
```
Then you can say:
``` ruby
2016-01-15 13:05:23 -05:00
describe MySpecialModel, type: :model do
2015-11-05 17:49:04 -05:00
# ...
end
```
#### `should` vs `is_expected.to`
2015-09-08 04:38:35 -04:00
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:
``` ruby
2015-11-06 09:48:04 -05:00
RSpec.describe Person, type: :model do
2015-09-08 04:38:35 -04:00
it { is_expected.to validate_presence_of(:name) }
end
```
2015-09-30 15:15:23 -04:00
### Minitest
2014-01-10 20:36:52 -05:00
2015-04-02 10:33:15 -04:00
Shoulda Matchers was originally a component of [Shoulda][shoulda], a gem that
also provides `should` and `context` syntax via
2016-01-10 00:58:24 -05:00
[`shoulda-context`][shoulda-context].
2016-01-27 06:23:47 -05:00
At the moment, `shoulda` has not been updated to support `shoulda-matchers` 3.x,
2016-01-10 00:58:24 -05:00
so you'll want to add the following to your Gemfile:
2014-01-10 20:36:52 -05:00
```ruby
group :test do
2015-10-05 12:40:21 -04:00
gem 'shoulda', '~> 3.5'
2016-01-10 00:58:24 -05:00
gem 'shoulda-matchers', '~> 2.0'
2014-01-10 20:36:52 -05:00
end
```
2015-04-02 10:33:15 -04:00
Now you can use matchers in your tests. For instance a model test might look
like this:
2014-01-10 20:36:52 -05:00
2015-04-02 10:33:15 -04:00
``` ruby
class PersonTest < ActiveSupport::TestCase
should validate_presence_of(:name)
end
2014-01-10 20:36:52 -05:00
```
2015-11-29 20:57:45 -05:00
## Running tests
### Unit tests
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
```
### Acceptance tests
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
```
### All tests
You can run all tests by saying:
```
bundle exec rake
```
2014-06-20 00:44:06 -04:00
## Generating documentation
2014-06-21 19:28:47 -04:00
YARD is used to generate documentation, which can be viewed [online][rubydocs].
You can preview changes you make to the documentation locally by running
2014-06-20 00:44:06 -04:00
yard doc
from this directory. Then, open `doc/index.html` in your browser.
2015-09-23 15:44:42 -04:00
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:
2014-06-20 00:44:06 -04:00
2015-09-23 15:44:42 -04:00
rake docs:autogenerate
2015-04-02 10:33:15 -04:00
## Contributing
Shoulda Matchers is open source, and we are grateful for
[everyone][contributors] who's contributed so far.
If you'd like to contribute, please take a look at the
[instructions ](CONTRIBUTING.md ) for installing dependencies and crafting a good
pull request.
2014-06-20 00:44:06 -04:00
2015-09-22 15:12:20 -04:00
## Compatibility
Shoulda Matchers is tested and supported against Rails 4.x, RSpec 3.x, Minitest
2016-01-04 13:29:14 -05:00
5, Minitest 4, and Ruby 2.x.
2015-09-22 15:12:20 -04:00
2013-10-23 15:27:08 -04:00
## Versioning
2015-04-02 10:33:15 -04:00
Shoulda Matchers follows Semantic Versioning 2.0 as defined at
2013-10-23 15:27:08 -04:00
< http: / / semver . org > .
2012-03-09 11:57:31 -05:00
## License
2016-01-04 13:29:14 -05:00
Shoulda Matchers is copyright © 2006-2016
2015-04-02 10:33:15 -04:00
[thoughtbot, inc ](https://thoughtbot.com/ ). It is free software,
2013-10-23 15:27:08 -04:00
and may be redistributed under the terms specified in the
[MIT-LICENSE ](MIT-LICENSE ) file.
2015-03-08 10:24:52 -04:00
## About thoughtbot
2017-03-10 09:41:08 -05:00
![thoughtbot ](http://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg )
2015-03-08 10:24:52 -04:00
2015-04-02 10:33:15 -04:00
Shoulda Matchers is maintained and funded by thoughtbot, inc.
2015-03-08 10:24:52 -04:00
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
We are passionate about open source software.
See [our other projects][community].
We are [available for hire][hire].
[community]: https://thoughtbot.com/community?utm_source=github
[hire]: https://thoughtbot.com?utm_source=github
2014-10-21 03:50:09 -04:00
[version-badge]: http://img.shields.io/gem/v/shoulda-matchers.svg
[rubygems]: http://rubygems.org/gems/shoulda-matchers
[travis-badge]: http://img.shields.io/travis/thoughtbot/shoulda-matchers/master.svg
2013-10-23 15:27:08 -04:00
[travis]: http://travis-ci.org/thoughtbot/shoulda-matchers
2014-10-21 03:50:09 -04:00
[downloads-badge]: http://img.shields.io/gem/dtv/shoulda-matchers.svg
2015-01-23 18:24:14 -05:00
[rubydocs]: http://matchers.shoulda.io/docs
2013-10-23 15:27:08 -04:00
[contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
2014-10-21 03:42:21 -04:00
[shoulda]: http://github.com/thoughtbot/shoulda
[shoulda-context]: http://github.com/thoughtbot/shoulda-context
2015-11-29 20:57:45 -05:00
[Zeus]: https://github.com/burke/zeus
[Appraisal]: https://github.com/thoughtbot/appraisal