shoulda-matchers 3.1.3 → 4.0.0.rc1

data/README.md

@@ -1,137 +1,50 @@
-# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge]
+# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge] [![Hound][hound-badge]][hound]
 
-[![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)
+[![shoulda-matchers][logo]][website]
 
 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 (3.1.1).][rubydocs]
+* [Documentation](#documentation)
+* [Compatibility](#compatibility)
+* [Getting started](#getting-started)
+   * [RSpec](#rspec)
+      * [Availability of matchers in various example groups](#availability-of-matchers-in-various-example-groups)
+      * [<code>should</code> vs <code>is_expected.to</code>](#should-vs-is_expectedto)
+   * [Minitest](#minitest)
+* [Matchers](#matchers)
+   * [ActiveModel matchers](#activemodel-matchers)
+   * [ActiveRecord matchers](#activerecord-matchers)
+   * [ActionController matchers](#actioncontroller-matchers)
+   * [Independent matchers](#independent-matchers)
+* [Contributing](#contributing)
+* [Versioning](#versioning)
+* [License](#license)
+* [About thoughtbot](#about-thoughtbot)
+
+## Documentation
+
+[View the official documentation for the latest version (4.0.0.rc1).][rubydocs]
 
-----
-
-### 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
-
-----
-
-### ActiveModel matchers
-
-* **[allow_mass_assignment_of](lib/shoulda/matchers/active_model/allow_mass_assignment_of_matcher.rb)**
-  tests usage of Rails 3's `attr_accessible` and `attr_protected` macros.
-* **[allow_value](lib/shoulda/matchers/active_model/allow_value_matcher.rb)**
-  tests that an attribute is valid or invalid if set to one or more values.
-  *(Aliased as #allow_values.)*
-* **[have_secure_password](lib/shoulda/matchers/active_model/have_secure_password_matcher.rb)**
-  tests usage of `has_secure_password`.
-* **[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`.
-* **[validate_confirmation_of](lib/shoulda/matchers/active_model/validate_confirmation_of_matcher.rb)**
-  tests usage of `validates_confirmation_of`.
-* **[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`.
-* **[validate_numericality_of](lib/shoulda/matchers/active_model/validate_numericality_of_matcher.rb)**
-  tests usage of `validates_numericality_of`.
-* **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
-  tests usage of `validates_presence_of`.
-
-### ActiveRecord matchers
-
-* **[accept_nested_attributes_for](lib/shoulda/matchers/active_record/accept_nested_attributes_for_matcher.rb)**
-  tests usage of the `accepts_nested_attributes_for` macro.
-* **[belong_to](lib/shoulda/matchers/active_record/association_matcher.rb)**
-  tests your `belongs_to` associations.
-* **[define_enum_for](lib/shoulda/matchers/active_record/define_enum_for_matcher.rb)**
-  tests usage of the `enum` macro.
-* **[have_and_belong_to_many](lib/shoulda/matchers/active_record/association_matcher.rb)**
-  tests your `has_and_belongs_to_many` associations.
-* **[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.
-* **[have_readonly_attribute](lib/shoulda/matchers/active_record/have_readonly_attribute_matcher.rb)**
-  tests usage of the `attr_readonly` macro.
-* **[serialize](lib/shoulda/matchers/active_record/serialize_matcher.rb)** tests
-  usage of the `serialize` macro.
-* **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
-  tests usage of `validates_uniqueness_of`.
-
-### ActionController matchers
-
-* **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
-  tests parameter filtering configuration.
-* **[permit](lib/shoulda/matchers/action_controller/permit_matcher.rb)** tests
-  that an action places a restriction on the `params` hash.
-* **[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.
-* **[set_flash](lib/shoulda/matchers/action_controller/set_flash_matcher.rb)**
-  makes assertions on the `flash` hash.
-* **[use_after_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L79)**
-  tests that an `after_action` callback is defined in your controller. *(Aliased
-  as #use_after_filter.)*
-* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L129)**
-  tests that an `around_action` callback is defined in your controller. *(Aliased
-  as #use_around_filter.)*
-* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L54)**
-  tests that a `before_action` callback is defined in your controller. *(Aliased
-  as #use_before_filter.)*
+## Compatibility
 
-### Independent matchers
+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+.
 
-* **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
-  tests that an object forwards messages to other, internal objects by way of
-  delegation.
+For Rails 4.0/4.1 and Ruby 2.0/2.1 compatibility, please use shoulda-matchers
+[3.1.2](https://github.com/thoughtbot/shoulda-matchers/releases/tag/v3.1.2).
 
 ## Getting started
 
 ### RSpec
 
-Include `shoulda-matchers` in your Gemfile:
-
-For Rails 4.x:
-
-``` ruby
-group :test do
-  gem 'shoulda-matchers', '~> 3.1'
-end
-```
-
-For Rails 5.0:
+Start by including `shoulda-matchers` in your Gemfile:
 
-``` ruby
+```ruby
 group :test do
-  gem 'shoulda-matchers', git: 'https://github.com/thoughtbot/shoulda-matchers.git', branch: 'rails-5'
+  gem 'shoulda-matchers', '4.0.0.rc1'
+  gem 'rails-controller-testing' # If you are using Rails 5.x
 end
 ```
 
@@ -143,7 +56,7 @@ Now you need to tell the gem a couple of things:
 You can supply this information by using a configuration block. Place the
 following in `rails_helper.rb`:
 
-``` ruby
+```ruby
 Shoulda::Matchers.configure do |config|
   config.integrate do |with|
     # Choose a test framework:
@@ -156,16 +69,16 @@ Shoulda::Matchers.configure do |config|
     with.library :active_record
     with.library :active_model
     with.library :action_controller
-    # Or, choose the following (which implies all of the above):
+    # 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
+Now you can use matchers in your tests. For instance, a model test might look
 like this:
 
-``` ruby
+```ruby
 RSpec.describe Person, type: :model do
   it { should validate_presence_of(:name) }
 end
@@ -190,7 +103,7 @@ different levels where you can use these matchers:
 to use model matchers in certain example groups, you'll need to manually include
 them. Here's a good way of doing that:
 
-``` ruby
+```ruby
 RSpec.configure do |config|
   config.include(Shoulda::Matchers::ActiveModel, type: :model)
   config.include(Shoulda::Matchers::ActiveRecord, type: :model)
@@ -199,7 +112,7 @@ end
 
 Then you can say:
 
-``` ruby
+```ruby
 describe MySpecialModel, type: :model do
   # ...
 end
@@ -213,7 +126,7 @@ 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
+```ruby
 RSpec.describe Person, type: :model do
   it { is_expected.to validate_presence_of(:name) }
 end
@@ -225,7 +138,7 @@ Shoulda Matchers was originally a component of [Shoulda][shoulda], a gem that
 also provides `should` and `context` syntax via
 [`shoulda-context`][shoulda-context].
 
-At the moment, `shoulda` has not been updated to support `shoulda-matchers` 3.x,
+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:
 
 ```ruby
@@ -238,72 +151,97 @@ end
 Now you can use matchers in your tests. For instance a model test might look
 like this:
 
-``` ruby
+```ruby
 class PersonTest < ActiveSupport::TestCase
   should validate_presence_of(:name)
 end
 ```
 
-## Running tests
-
-### Unit tests
+## Matchers
 
-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:
+### ActiveModel matchers
 
-```
-bundle exec rake
-```
+* **[allow_value](lib/shoulda/matchers/active_model/allow_value_matcher.rb)**
+  tests that an attribute is valid or invalid if set to one or more values.
+  *(Aliased as #allow_values.)*
+* **[have_secure_password](lib/shoulda/matchers/active_model/have_secure_password_matcher.rb)**
+  tests usage of `has_secure_password`.
+* **[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`.
+* **[validate_confirmation_of](lib/shoulda/matchers/active_model/validate_confirmation_of_matcher.rb)**
+  tests usage of `validates_confirmation_of`.
+* **[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`.
+* **[validate_numericality_of](lib/shoulda/matchers/active_model/validate_numericality_of_matcher.rb)**
+  tests usage of `validates_numericality_of`.
+* **[validate_presence_of](lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb)**
+  tests usage of `validates_presence_of`.
 
-## Generating documentation
+### ActiveRecord matchers
 
-YARD is used to generate documentation, which can be viewed [online][rubydocs].
-You can preview changes you make to the documentation locally by running
+* **[accept_nested_attributes_for](lib/shoulda/matchers/active_record/accept_nested_attributes_for_matcher.rb)**
+  tests usage of the `accepts_nested_attributes_for` macro.
+* **[belong_to](lib/shoulda/matchers/active_record/association_matcher.rb)**
+  tests your `belongs_to` associations.
+* **[define_enum_for](lib/shoulda/matchers/active_record/define_enum_for_matcher.rb)**
+  tests usage of the `enum` macro.
+* **[have_and_belong_to_many](lib/shoulda/matchers/active_record/association_matcher.rb)**
+  tests your `has_and_belongs_to_many` associations.
+* **[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.
+* **[have_readonly_attribute](lib/shoulda/matchers/active_record/have_readonly_attribute_matcher.rb)**
+  tests usage of the `attr_readonly` macro.
+* **[serialize](lib/shoulda/matchers/active_record/serialize_matcher.rb)** tests
+  usage of the `serialize` macro.
+* **[validate_uniqueness_of](lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb)**
+  tests usage of `validates_uniqueness_of`.
 
-    yard doc
+### ActionController matchers
 
-from this directory. Then, open `doc/index.html` in your browser.
+* **[filter_param](lib/shoulda/matchers/action_controller/filter_param_matcher.rb)**
+  tests parameter filtering configuration.
+* **[permit](lib/shoulda/matchers/action_controller/permit_matcher.rb)** tests
+  that an action places a restriction on the `params` hash.
+* **[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.
+* **[set_flash](lib/shoulda/matchers/action_controller/set_flash_matcher.rb)**
+  makes assertions on the `flash` hash.
+* **[use_after_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L79)**
+  tests that an `after_action` callback is defined in your controller.
+* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L129)**
+  tests that an `around_action` callback is defined in your controller.
+* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L54)**
+  tests that a `before_action` callback is defined in your controller.
 
-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:
+### Independent matchers
 
-    rake docs:autogenerate
+* **[delegate_method](lib/shoulda/matchers/independent/delegate_method_matcher.rb)**
+  tests that an object forwards messages to other, internal objects by way of
+  delegation.
 
 ## Contributing
 
@@ -314,11 +252,6 @@ If you'd like to contribute, please take a look at the
 [instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
 pull request.
 
-## Compatibility
-
-Shoulda Matchers is tested and supported against Rails 4.x, RSpec 3.x, Minitest
-5, Minitest 4, and Ruby 2.x.
-
 ## Versioning
 
 Shoulda Matchers follows Semantic Versioning 2.0 as defined at
@@ -326,32 +259,37 @@ Shoulda Matchers follows Semantic Versioning 2.0 as defined at
 
 ## License
 
-Shoulda Matchers is copyright © 2006-2016
-[thoughtbot, inc](https://thoughtbot.com/). It is free software,
+Shoulda Matchers is copyright © 2006-2018
+[thoughtbot, inc][thoughtbot-website]. It is free software,
 and may be redistributed under the terms specified in the
 [MIT-LICENSE](MIT-LICENSE) file.
 
 ## About thoughtbot
 
-![thoughtbot](http://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg)
+![thoughtbot][thoughtbot-logo]
 
-Shoulda Matchers is maintained and funded by thoughtbot, inc.
-The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+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][community].
-We are [available for hire][hire].
+We are passionate about open source software. See [our other
+projects][community]. We are [available for hire][hire].
 
+[rubydocs]: http://matchers.shoulda.io/docs/v4.0.0.rc1
 [community]: https://thoughtbot.com/community?utm_source=github
 [hire]: https://thoughtbot.com?utm_source=github
-[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
-[travis]: http://travis-ci.org/thoughtbot/shoulda-matchers
-[downloads-badge]: http://img.shields.io/gem/dtv/shoulda-matchers.svg
-[rubydocs]: http://matchers.shoulda.io/docs
+[version-badge]: https://img.shields.io/gem/v/shoulda-matchers.svg
+[rubygems]: httpss://rubygems.org/gems/shoulda-matchers
+[travis-badge]: https://img.shields.io/travis/thoughtbot/shoulda-matchers/master.svg
+[travis]: https://travis-ci.org/thoughtbot/shoulda-matchers
+[downloads-badge]: https://img.shields.io/gem/dtv/shoulda-matchers.svg
 [contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
-[shoulda]: http://github.com/thoughtbot/shoulda
-[shoulda-context]: http://github.com/thoughtbot/shoulda-context
+[shoulda]: https://github.com/thoughtbot/shoulda
+[shoulda-context]: https://github.com/thoughtbot/shoulda-context
 [Zeus]: https://github.com/burke/zeus
 [Appraisal]: https://github.com/thoughtbot/appraisal
+[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
+[hound]: https://houndci.com
+[thoughtbot-website]: https://thoughtbot.com
+[thoughtbot-logo]: https://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg
+[logo]: https://matchers.shoulda.io/images/shoulda-matchers-logo.png
+[website]: https://matchers.shoulda.io/

data/Rakefile

@@ -34,6 +34,13 @@ task :default do
   end
 end
 
+namespace :appraisal do
+  task :list do
+    appraisals = Tests::CurrentBundle.instance.available_appraisals
+    puts "Valid appraisals: #{appraisals.join(', ')}"
+  end
+end
+
 Shoulda::Matchers::DocumentationTasks.create
 
 task release: 'docs:publish_latest'