shoulda-matchers 4.3.0 → 5.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c022366c394fe10215171aee752452d41f7e051ef0174b99e0d9f947486ac1f7
-  data.tar.gz: 38bc2bf3e4d8432ebc8a8c1bfb319fc1da9236699e1ec28d78b53d93621c96c2
+  metadata.gz: b4bebbe2dbe599d4b1c19061803f12abb87578322e17a96a56d0442399ef72a9
+  data.tar.gz: 4742002f75d6cc61f6eb4419a4729632c000519ff1bd1e9c52754c251835294d
 SHA512:
-  metadata.gz: e06ce93032d5612eb34c952eb310f199b718e35875ae31c84ae177a09ca2bbdcc5fe33cc8fc3a97f5bf77aa3c5e2c91e3f7596e8c6328c66e494c8a9f3a94d90
-  data.tar.gz: 10f26b7b206227be842077802b9da370775b198cf30f32e8df70fa1b1bb69cbddd831244071eab874d98e186c6abee7a8c11187015f65b8f1f570b47ba20e947
+  metadata.gz: 7b7c3f78337afc8da72887fa743956839d637e6eb277b0c6ba06a55837468b4ec598ae1bf534b58c9287b5b3e381e7ffe228a19b32a78c434f1048ffa6378441
+  data.tar.gz: 5944d64e1ab63143363ad0a2ee1f32fe761178664fe2e1bff38b71b324341719ec48619cc687d1b185dc1544e32badc65a21f16c694b33147db100fd93a33d2e

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2020, Tammer Saleh and thoughtbot, inc.
+Copyright (c) 2006-2021 Tammer Saleh and thoughtbot, inc.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -1,14 +1,12 @@
-# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] [![Total Downloads][downloads-total]][rubygems] [![Downloads][downloads-badge]][rubygems] [![Hound][hound-badge]][hound]
+# Shoulda Matchers [![Gem Version][version-badge]][rubygems] [![Build Status][github-actions-badge]][github-actions] [![Total Downloads][downloads-total]][rubygems] [![Downloads][downloads-badge]][rubygems]
 
 [version-badge]: https://img.shields.io/gem/v/shoulda-matchers.svg
 [rubygems]: https://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
+[github-actions-badge]: https://img.shields.io/github/workflow/status/thoughtbot/shoulda-matchers/Test
+[github-actions]: https://github.com/thoughtbot/shoulda-matchers/actions
 [downloads-total]: https://img.shields.io/gem/dt/shoulda-matchers.svg
 [downloads-badge]: https://img.shields.io/gem/dtv/shoulda-matchers.svg
 [downloads-badge]: https://img.shields.io/gem/dtv/shoulda-matchers.svg
-[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
-[hound]: https://houndci.com
 
 [![shoulda-matchers][logo]][website]
 
@@ -22,10 +20,10 @@ complex, and error-prone.
 ## Quick links
 
 📖 **[Read the documentation for the latest version][rubydocs].**  
-📢 **[See what's changed in a recent version][news].**
+📢 **[See what's changed in recent versions][changelog].**
 
-[rubydocs]: http://matchers.shoulda.io/docs
-[news]: NEWS.md
+[rubydocs]: https://matchers.shoulda.io/docs
+[changelog]: CHANGELOG.md
 
 ## Table of contents
 
@@ -41,10 +39,12 @@ complex, and error-prone.
    * [ActiveRecord matchers](#activerecord-matchers)
    * [ActionController matchers](#actioncontroller-matchers)
    * [Independent matchers](#independent-matchers)
-* [Compatibility](#compatibility)
+* [Extensions](#extensions)
 * [Contributing](#contributing)
+* [Compatibility](#compatibility)
 * [Versioning](#versioning)
-* [License](#license)
+* [Team](#team)
+* [Copyright/License](#copyright-license)
 * [About thoughtbot](#about-thoughtbot)
 
 ## Getting started
@@ -55,21 +55,21 @@ Start by including `shoulda-matchers` in your Gemfile:
 
 ```ruby
 group :test do
-  gem 'shoulda-matchers'
+  gem 'shoulda-matchers', '~> 4.0'
 end
 ```
 
-Now you need to tell the gem a couple of things:
+Then run `bundle install`.
 
-* Which test framework you're using
-* Which portion of the matchers you want to use
+Now you need to configure the gem by telling it:
 
-You can supply this information by providing a configuration block. Where this
-goes and what this contains depends on your project.
+* which matchers you want to use in your tests
+* that you're using RSpec so that it can make those matchers available in
+  your example groups
 
 #### Rails apps
 
-Assuming you are testing a Rails app, simply place this at the bottom of
+If you're working on a Rails app, simply place this at the bottom of
 `spec/rails_helper.rb` (or in a support file if you so choose):
 
 ```ruby
@@ -81,13 +81,12 @@ Shoulda::Matchers.configure do |config|
 end
 ```
 
-Now you're ready to [use matchers in your tests](#usage)!
-
 #### Non-Rails apps
 
-If your project isn't a Rails app, but you still make use of ActiveRecord or
-ActiveModel, you can still use this gem too! In that case, you'll want to place
-the following configuration at the bottom of `spec/spec_helper.rb`:
+If you're not working on a Rails app, but you still make use of ActiveRecord or
+ActiveModel in your project, you can still use this gem too! In that case,
+you'll want to place the following configuration at the bottom of
+`spec/spec_helper.rb`:
 
 ```ruby
 Shoulda::Matchers.configure do |config|
@@ -101,45 +100,83 @@ Shoulda::Matchers.configure do |config|
 end
 ```
 
-Now you're ready to [use matchers in your tests](#usage)!
-
 ### Minitest
 
-Shoulda Matchers was originally a component of [Shoulda][shoulda], a gem that
-also provides `should` and `context` syntax via
-[`shoulda-context`][shoulda-context].
+If you're using our umbrella gem [Shoulda], then make sure that you're using the
+latest version:
 
-[shoulda]: https://github.com/thoughtbot/shoulda
-[shoulda-context]: https://github.com/thoughtbot/shoulda-context
+```ruby
+group :test do
+  gem 'shoulda', '~> 4.0'
+end
+```
+
+[Shoulda]: https://github.com/thoughtbot/shoulda
 
-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:
+Otherwise, add `shoulda-matchers` to your Gemfile:
 
 ```ruby
 group :test do
-  gem 'shoulda', '~> 3.5'
-  gem 'shoulda-matchers', '~> 2.0'
-  gem 'rails-controller-testing'
+  gem 'shoulda-matchers', '~> 4.0'
+end
+```
+
+Then run `bundle install`.
+
+Now you need to configure the gem by telling it:
+
+* which matchers you want to use in your tests
+* that you're using Minitest so that it can make those matchers available in
+  your test case classes
+
+#### Rails apps
+
+If you're working on a Rails app, simply place this at the bottom of
+`test/test_helper.rb`:
+
+```ruby
+Shoulda::Matchers.configure do |config|
+  config.integrate do |with|
+    with.test_framework :minitest
+    with.library :rails
+  end
 end
 ```
 
-Now you're ready to [use matchers in your tests](#usage)!
+#### Non-Rails apps
+
+If you're not working on a Rails app, but you still make use of ActiveRecord or
+ActiveModel in your project, you can still use this gem too! In that case,
+you'll want to place the following configuration at the bottom of
+`test/test_helper.rb`:
+
+```ruby
+Shoulda::Matchers.configure do |config|
+  config.integrate do |with|
+    with.test_framework :minitest
+
+    # Keep as many of these lines as are necessary:
+    with.library :active_record
+    with.library :active_model
+  end
+end
+```
 
 ## Usage
 
-The matchers provided by this gem are divided into different categories
-depending on what you're testing within your Rails app:
+Most of the matchers provided by this gem are useful in a Rails context, and as
+such, can be used for different parts of a Rails app:
 
 * [database models backed by ActiveRecord](#activemodel-matchers)
 * [non-database models, form objects, etc. backed by
   ActiveModel](#activerecord-matchers)
 * [controllers](#actioncontroller-matchers)
 * [routes](#routing-matchers) (RSpec only)
-* [usage of Rails-specific features like `delegate`](#independent-matchers)
+* [Rails-specific features like `delegate`](#independent-matchers)
 
-All matchers are designed to be prepended primarily with the word `should`,
-which is a special directive in both RSpec and Shoulda. For instance, a model
-test case may look something like:
+As the name of the gem indicates, most matchers are designed to be used in
+"one-liner" form using the `should` macro, a special directive available in both
+RSpec and [Shoulda]. For instance, a model test case may look something like:
 
 ``` ruby
 # RSpec
@@ -167,16 +204,17 @@ class MenuItemTest < ActiveSupport::TestCase
 end
 ```
 
-For the full set of matchers you can use, [see below](#matchers).
+[See below](#matchers) for the full set of matchers that you can use.
 
 ### On the subject of `subject`
 
 For both RSpec and Shoulda, the **subject** is an implicit reference to the
-object under test, and all of the matchers make use of it internally when they
-are run. This is always set automatically by your test framework in any given
-test case; however, in certain cases it can be advantageous to override the
-subject. For instance, when testing validations in a model, it is customary to
-provide a valid model instead of a fresh one:
+object under test, and through the use of `should` as demonstrated above, all of
+the matchers make use of `subject` internally when they are run. A `subject` is
+always set automatically by your test framework in any given test case; however,
+in certain cases it can be advantageous to override it. For instance, when
+testing validations in a model, it is customary to provide a valid model instead
+of a fresh one:
 
 ``` ruby
 # RSpec
@@ -234,11 +272,19 @@ end
 
 ### Availability of RSpec matchers in example groups
 
+#### Rails projects
+
 If you're using RSpec, then you're probably familiar with the concept of example
-groups: these are different kinds of test cases, and each of them has special
-behavior around them. As alluded to [above](#usage), this gem works in a similar
-way, and there are matchers that are only available in certain types of example
-groups:
+groups. Example groups can be assigned tags order to assign different behavior
+to different kinds of example groups. This comes into play especially when using
+`rspec-rails`, where, for instance, controller example groups, tagged with
+`type: :controller`, are written differently than request example groups, tagged
+with `type: :request`. This difference in writing style arises because
+`rspec-rails` mixes different behavior and methods into controller example
+groups vs. request example groups.
+
+Relying on this behavior, Shoulda Matchers automatically makes certain matchers
+available in certain kinds of example groups:
 
 * ActiveRecord and ActiveModel matchers are available only in model example
   groups, i.e., those tagged with `type: :model` or in files located under
@@ -250,13 +296,27 @@ groups:
   tagged with `type: :routing` or in files located under `spec/routing`.
 * Independent matchers are available in all example groups.
 
-As long as you're using Rails, you don't need to worry about this — everything
-should "just work".
+As long as you're using Rails, you don't need to worry about these details —
+everything should "just work".
+
+#### Non-Rails projects
 
-**However, 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 the module that holds those matchers. A good way to do this is
-to place the following in your `spec_helper.rb`:
+**What if you are using ActiveModel or ActiveRecord outside of Rails, however,
+and you want to use model matchers in a certain example group?** Then you'll
+need to manually include the module that holds those matchers into that example
+group. For instance, you might have to say:
+
+``` ruby
+RSpec.describe MySpecialModel do
+  include Shoulda::Matchers::ActiveModel
+  include Shoulda::Matchers::ActiveRecord
+end
+```
+
+If you have a lot of similar example groups in which you need to do this, then
+you might find it more helpful to tag your example groups appropriately, then
+instruct RSpec to mix these modules into any example groups that have that tag.
+For instance, you could add this to your `rails_helper.rb`:
 
 ```ruby
 RSpec.configure do |config|
@@ -265,21 +325,20 @@ RSpec.configure do |config|
 end
 ```
 
-Then you can say:
+And from then on, you could say:
 
 ```ruby
-describe MySpecialModel, type: :model do
+RSpec.describe MySpecialModel, type: :model do
   # ...
 end
 ```
 
 ### `should` vs `is_expected.to`
 
-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:
+In this README and throughout the documentation, you'll notice that we use the
+`should` form of RSpec's one-liner syntax over `is_expected.to`. Beside being
+the namesake of the gem itself, this is our preferred syntax as it's short and
+sweet. But if you prefer to use `is_expected.to`, you can do that too:
 
 ```ruby
 RSpec.describe Person, type: :model do
@@ -289,7 +348,7 @@ end
 
 ## Matchers
 
-The following is a list of matchers shipped with the gem. If you need details
+Here is the full list of matchers that ship with this gem. If you need details
 about any of them, make sure to [consult the documentation][rubydocs]!
 
 ### ActiveModel matchers
@@ -324,16 +383,22 @@ about any of them, make sure to [consult the documentation][rubydocs]!
   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)**
+* **[have_and_belong_to_many](lib/shoulda/matchers/active_record/association_matcher.rb#L827)**
   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)**
+* **[have_implicit_order_column](lib/shoulda/matchers/active_record/have_implicit_order_column.rb)**
+  tests usage of `implicit_order_column`.
+* **[have_many](lib/shoulda/matchers/active_record/association_matcher.rb#L328)**
   tests your `has_many` associations.
-* **[have_one](lib/shoulda/matchers/active_record/association_matcher.rb)**
+* **[have_many_attached](lib/shoulda/matchers/active_record/have_attached_matcher.rb)**
+  tests your `has_many_attached` associations.
+* **[have_one](lib/shoulda/matchers/active_record/association_matcher.rb#L598)**
   tests your `has_one` associations.
+* **[have_one_attached](lib/shoulda/matchers/active_record/have_attached_matcher.rb)**
+  tests your `has_one_attached` associations.
 * **[have_readonly_attribute](lib/shoulda/matchers/active_record/have_readonly_attribute_matcher.rb)**
   tests usage of the `attr_readonly` macro.
 * **[have_rich_text](lib/shoulda/matchers/active_record/have_rich_text_matcher.rb)**
@@ -365,11 +430,11 @@ about any of them, make sure to [consult the documentation][rubydocs]!
   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)**
+* **[use_after_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L29)**
   tests that an `after_action` callback is defined in your controller.
-* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L129)**
+* **[use_around_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L75)**
   tests that an `around_action` callback is defined in your controller.
-* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L54)**
+* **[use_before_action](lib/shoulda/matchers/action_controller/callback_matcher.rb#L4)**
   tests that a `before_action` callback is defined in your controller.
 
 ### Routing matchers
@@ -383,37 +448,53 @@ about any of them, make sure to [consult the documentation][rubydocs]!
   tests that an object forwards messages to other, internal objects by way of
   delegation.
 
-## Compatibility
+## Extensions
 
-Shoulda Matchers is tested and supported against Ruby 2.4+, Rails 5.x, Rails
-4.2.x, RSpec 3.x, and Minitest 5.x.
+Over time our community has created extensions to Shoulda Matchers. If you've
+created something that you want to share, please [let us know][new-issue]!
 
-For Ruby < 2.4 and Rails < 4.1 compatibility, please use [v3.1.3][v3.1.3].
+* **[shoulda-matchers-cucumber]** – Adds support for using Shoulda Matchers in
+  Cucumber tests.
 
-[v3.1.3]: https://github.com/thoughtbot/shoulda-matchers/releases/tag/v3.1.3
+[new-issue]: https://github.com/thoughtbot/shoulda-matchers/issues/new
+[shoulda-matchers-cucumber]: https://github.com/majioa/shoulda-matchers-cucumber
 
 ## Contributing
 
-Shoulda Matchers is open source, and we are grateful for
-[everyone][contributors] who's contributed so far.
+Have a fix for a problem you've been running into or an idea for a new feature
+you think would be useful? Take a look at the [Contributing
+document](CONTRIBUTING.md) for instructions on setting up the repo on your
+machine, understanding the codebase, and creating a good pull request.
 
-[contributors]: https://github.com/thoughtbot/shoulda-matchers/contributors
+## Compatibility
+
+Shoulda Matchers is tested and supported against Ruby 2.6+, Rails
+5.2+, RSpec 3.x, and Minitest 5.x.
+
+- For Ruby < 2.4 and Rails < 4.1 compatibility, please use [v3.1.3][v3.1.3].
+- For Ruby < 3.0 and Rails < 6.1 compatibility, please use [v4.5.1][v4.5.1].
 
-If you'd like to contribute, please take a look at the
-[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
-pull request.
+[v3.1.3]: https://github.com/thoughtbot/shoulda-matchers/tree/v3.1.3
+[v4.5.1]: https://github.com/thoughtbot/shoulda-matchers/tree/v4.5.1
 
 ## Versioning
 
 Shoulda Matchers follows Semantic Versioning 2.0 as defined at
-<http://semver.org>.
+<https://semver.org>.
+
+## Team
+
+Shoulda Matchers is maintained by [Elliot Winkler][mcmire] and [Gui
+Albuk][guialbuk].
+
+[mcmire]: https://github.com/mcmire
+[guialbuk]: https://github.com/guialbuk
 
-## License
+## Copyright/License
 
-Shoulda Matchers is copyright © 2006-2020
-[thoughtbot, inc][thoughtbot-website]. It is free software,
-and may be redistributed under the terms specified in the
-[MIT-LICENSE](MIT-LICENSE) file.
+Shoulda Matchers is copyright © 2006-2021 Tammer Saleh and [thoughtbot,
+inc][thoughtbot-website]. It is free and opensource software and may be
+redistributed under the terms specified in the [LICENSE](LICENSE) file.
 
 [thoughtbot-website]: https://thoughtbot.com
 
@@ -423,8 +504,7 @@ and may be redistributed under the terms specified in the
 
 [thoughtbot-logo]: https://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg
 
-Shoulda Matchers is maintained and funded by thoughtbot, inc. The names and
-logos for thoughtbot are trademarks of 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].

data/lib/shoulda/matchers/action_controller/callback_matcher.rb

@@ -1,64 +1,6 @@
 module Shoulda
   module Matchers
     module ActionController
-      # The `use_before_filter` matcher is used to test that a before_filter
-      # callback is defined within your controller.
-      #
-      #     class UsersController < ApplicationController
-      #       before_filter :authenticate_user!
-      #     end
-      #
-      #     # RSpec
-      #     RSpec.describe UsersController, type: :controller do
-      #       it { should use_before_filter(:authenticate_user!) }
-      #       it { should_not use_before_filter(:prevent_ssl) }
-      #     end
-      #
-      #     # Minitest (Shoulda)
-      #     class UsersControllerTest < ActionController::TestCase
-      #       should use_before_filter(:authenticate_user!)
-      #       should_not use_before_filter(:prevent_ssl)
-      #     end
-      #
-      # @note This method is only available when using shoulda-matchers under
-      # Rails 4.x.
-      # @return [CallbackMatcher]
-      #
-      if RailsShim.action_pack_lt_5?
-        def use_before_filter(callback)
-          CallbackMatcher.new(callback, :before, :filter)
-        end
-      end
-
-      # The `use_after_filter` matcher is used to test that an after_filter
-      # callback is defined within your controller.
-      #
-      #     class IssuesController < ApplicationController
-      #       after_filter :log_activity
-      #     end
-      #
-      #     # RSpec
-      #     RSpec.describe IssuesController, type: :controller do
-      #       it { should use_after_filter(:log_activity) }
-      #       it { should_not use_after_filter(:destroy_user) }
-      #     end
-      #
-      #     # Minitest (Shoulda)
-      #     class IssuesControllerTest < ActionController::TestCase
-      #       should use_after_filter(:log_activity)
-      #       should_not use_after_filter(:destroy_user)
-      #     end
-      #
-      # @note This method is only available when using shoulda-matchers under
-      # Rails 4.x.
-      # @return [CallbackMatcher]
-      #
-      if RailsShim.action_pack_lt_5?
-        def use_after_filter(callback)
-          CallbackMatcher.new(callback, :after, :filter)
-        end
-      end
-
       # The `use_before_action` matcher is used to test that a before_action
       # callback is defined within your controller.
       #
@@ -109,35 +51,6 @@ module Shoulda
         CallbackMatcher.new(callback, :after, :action)
       end
 
-      # The `use_around_filter` matcher is used to test that an around_filter
-      # callback is defined within your controller.
-      #
-      #     class ChangesController < ApplicationController
-      #       around_filter :wrap_in_transaction
-      #     end
-      #
-      #     # RSpec
-      #     RSpec.describe ChangesController, type: :controller do
-      #       it { should use_around_filter(:wrap_in_transaction) }
-      #       it { should_not use_around_filter(:save_view_context) }
-      #     end
-      #
-      #     # Minitest (Shoulda)
-      #     class ChangesControllerTest < ActionController::TestCase
-      #       should use_around_filter(:wrap_in_transaction)
-      #       should_not use_around_filter(:save_view_context)
-      #     end
-      #
-      # @note This method is only available when using shoulda-matchers under
-      # Rails 4.x.
-      # @return [CallbackMatcher]
-      #
-      if RailsShim.action_pack_lt_5?
-        def use_around_filter(callback)
-          CallbackMatcher.new(callback, :around, :filter)
-        end
-      end
-
       # The `use_around_action` matcher is used to test that an around_action
       # callback is defined within your controller.
       #
@@ -179,11 +92,13 @@ module Shoulda
         end
 
         def failure_message
-          "Expected that #{controller_class.name} would have :#{method_name} as a #{kind}_#{callback_type}"
+          "Expected that #{controller_class.name} would have :#{method_name}"\
+            " as a #{kind}_#{callback_type}"
         end
 
         def failure_message_when_negated
-          "Expected that #{controller_class.name} would not have :#{method_name} as a #{kind}_#{callback_type}"
+          "Expected that #{controller_class.name} would not have"\
+            " :#{method_name} as a #{kind}_#{callback_type}"
         end
 
         def description