shoulda-matchers 4.0.0.rc1 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3638e6c8356a1c93b6e33b3b0dfcab34c5a5d3646567e3c91f553c490f93d52
-  data.tar.gz: 10afc07f98e5609023024ad215cd14bdbd51a25a9c628a8ee9375c6d644e6d32
+  metadata.gz: 6e90bda8ad7aa6bef803eddafa1a0aee31f4228372a5d4ba30255682cc841ed6
+  data.tar.gz: 33c33b0e10964e0dfd3d80e9e680b361a96f817205cd513786779593e3681ae7
 SHA512:
-  metadata.gz: ad1528def76b90a6dfdabc272b32a62393717a4e2ce386fb7b859a2a0a43bb5d92521a446ba9da26fe7a8a5e7451869e9f9840f57cde202e78ef67493823d7d2
-  data.tar.gz: 5ee29e5681bf5e788ee9ba85d1e7f29eb77fe538b92f82b8477f42cc317c6d2d3db3072a73a531f02f18f6710bb189478d0bc855f7cfbbb56bafe293a4d43cce
+  metadata.gz: 71099155dc17393673681f6255d4dc52735182de139ccf798939b2a3f8ea310e5547286f91ddbd914b98d58fccb7cecc2a0277ecdab1febd6ecf7b918de888b0
+  data.tar.gz: 1b4624af4740f43192336f624f748c3506131d1ce57f29c65591dce5f0ceee8e0d12a5860a81ddadadec4e423e94662f166a5d91dc7df82050d53353e82994a7

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2018, Tammer Saleh and thoughtbot, inc.
+Copyright (c) 2006-2019, 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

@@ -3,11 +3,13 @@
 [![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.
+common Rails functionality. These tests, if written by hand, would be much
+longer, more complex, and error-prone.
+
+**[View the documentation for the latest version (4.0.0).][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)
@@ -18,23 +20,12 @@ complex, and error-prone.
    * [ActiveRecord matchers](#activerecord-matchers)
    * [ActionController matchers](#actioncontroller-matchers)
    * [Independent matchers](#independent-matchers)
+* [Compatibility](#compatibility)
 * [Contributing](#contributing)
 * [Versioning](#versioning)
 * [License](#license)
 * [About thoughtbot](#about-thoughtbot)
 
-## Documentation
-
-[View the official documentation for the latest version (4.0.0.rc1).][rubydocs]
-
-## Compatibility
-
-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+.
-
-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
@@ -43,8 +34,8 @@ Start by including `shoulda-matchers` in your Gemfile:
 
 ```ruby
 group :test do
-  gem 'shoulda-matchers', '4.0.0.rc1'
-  gem 'rails-controller-testing' # If you are using Rails 5.x
+  gem 'shoulda-matchers'
+  gem 'rails-controller-testing'
 end
 ```
 
@@ -53,30 +44,52 @@ 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`:
+You can supply this information by providing a configuration block. Where this
+goes and what this contains depends on your project.
+
+#### Rails apps
+
+Assuming you are testing a Rails app, simply place this at the bottom of
+`spec/rails_helper.rb` (or in a support file if you so choose):
 
 ```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
+    with.library :rails
+  end
+end
+```
+
+Now you're ready to use matchers in your tests! For instance, you might decide
+to add a matcher to one of your models:
 
-    # Choose one or more libraries:
+```ruby
+RSpec.describe Person, type: :model do
+  it { should validate_presence_of(:name) }
+end
+```
+
+#### 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`:
+
+```ruby
+Shoulda::Matchers.configure do |config|
+  config.integrate do |with|
+    with.test_framework :rspec
+
+    # Keep as many of these lines as are necessary:
     with.library :active_record
     with.library :active_model
-    with.library :action_controller
-    # 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
-like this:
+Now you're ready to use matchers in your tests! For instance, you might decide
+to add a matcher to one of your models:
 
 ```ruby
 RSpec.describe Person, type: :model do
@@ -84,10 +97,14 @@ RSpec.describe Person, type: :model do
 end
 ```
 
+For more of an idea of what you can use, [see the list of matchers
+below](#matchers).
+
 #### 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:
+Regardless of your project, it's important to keep in mind that 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
@@ -99,11 +116,13 @@ different levels where you can use these matchers:
   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
+**⚠️ 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
+require 'shoulda-matchers'
+
 RSpec.configure do |config|
   config.include(Shoulda::Matchers::ActiveModel, type: :model)
   config.include(Shoulda::Matchers::ActiveRecord, type: :model)
@@ -122,8 +141,8 @@ end
 
 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
+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
@@ -138,8 +157,8 @@ 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 and 4.x,
-so you'll want to add the following to your Gemfile:
+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
 group :test do
@@ -148,8 +167,8 @@ group :test do
 end
 ```
 
-Now you can use matchers in your tests. For instance a model test might look
-like this:
+Now you're ready to use matchers in your tests! For instance, you might decide
+to add a matcher to one of your models:
 
 ```ruby
 class PersonTest < ActiveSupport::TestCase
@@ -157,6 +176,9 @@ class PersonTest < ActiveSupport::TestCase
 end
 ```
 
+For more of an idea of what you can use, [see the list of matchers
+below](#matchers).
+
 ## Matchers
 
 ### ActiveModel matchers
@@ -243,6 +265,16 @@ end
   tests that an object forwards messages to other, internal objects by way of
   delegation.
 
+## Compatibility
+
+Shoulda Matchers 4 is tested and supported against Rails 5.x, Rails 4.2, RSpec
+3.x, Minitest 5, Minitest 4, and Ruby 2.3+.
+
+For Rails 4.0/4.1 and Ruby 2.0/2.1/2.2 compatibility, please use
+[shoulda-matchers 3.1.3][v3.1.3].
+
+[v3.1.3]: https://github.com/thoughtbot/shoulda-matchers/releases/tag/v3.1.3
+
 ## Contributing
 
 Shoulda Matchers is open source, and we are grateful for
@@ -259,7 +291,7 @@ Shoulda Matchers follows Semantic Versioning 2.0 as defined at
 
 ## License
 
-Shoulda Matchers is copyright © 2006-2018
+Shoulda Matchers is copyright © 2006-2019
 [thoughtbot, inc][thoughtbot-website]. It is free software,
 and may be redistributed under the terms specified in the
 [MIT-LICENSE](MIT-LICENSE) file.

data/lib/shoulda/matchers/action_controller.rb

@@ -16,6 +16,8 @@ require 'shoulda/matchers/action_controller/session_store'
 
 module Shoulda
   module Matchers
+    # This module provides matchers that are used to test behavior within
+    # controllers.
     module ActionController
     end
   end

data/lib/shoulda/matchers/active_model.rb

@@ -32,9 +32,8 @@ require 'shoulda/matchers/active_model/have_secure_password_matcher'
 
 module Shoulda
   module Matchers
-    # This mixin provides matchers that are used to test behavior, such as
-    # validations, that you've added to your ActiveModel (or ActiveRecord)
-    # objects.
+    # This module provides matchers that are used to test behavior within
+    # ActiveModel or ActiveRecord classes.
     #
     # ### Testing conditional validations
     #

data/lib/shoulda/matchers/active_model/validate_inclusion_of_matcher.rb

@@ -322,6 +322,7 @@ EOT
 
         def allow_nil
           @options[:allow_nil] = true
+          self
         end
 
         def expects_to_allow_nil?

data/lib/shoulda/matchers/active_record.rb

@@ -24,6 +24,8 @@ require "shoulda/matchers/active_record/validate_uniqueness_of_matcher"
 
 module Shoulda
   module Matchers
+    # This module provides matchers that are used to test behavior within
+    # ActiveRecord classes.
     module ActiveRecord
     end
   end

data/lib/shoulda/matchers/active_record/association_matcher.rb

@@ -272,6 +272,35 @@ module Shoulda
       #       should belong_to(:organization).required
       #     end
       #
+      # #### without_validating_presence
+      #
+      # Use `without_validating_presence` with `belong_to` to prevent the
+      # matcher from checking whether the association disallows nil (Rails 5+
+      # only). This can be helpful if you have a custom hook that always sets
+      # the association to a meaningful value:
+      #
+      #     class Person < ActiveRecord::Base
+      #       belongs_to :organization
+      #
+      #       before_validation :autoassign_organization
+      #
+      #       private
+      #
+      #       def autoassign_organization
+      #         self.organization = Organization.create!
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe Person
+      #       it { should belong_to(:organization).without_validating_presence }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should belong_to(:organization).without_validating_presence
+      #     end
+      #
       # ##### optional
       #
       # Use `optional` to assert that the association is allowed to be nil.
@@ -1092,6 +1121,11 @@ module Shoulda
           self
         end
 
+        def without_validating_presence
+          remove_submatcher(AssociationMatchers::RequiredMatcher)
+          self
+        end
+
         def description
           description = "#{macro_description} #{name}"
           description += " class_name => #{options[:class_name]}" if options.key?(:class_name)

data/lib/shoulda/matchers/active_record/association_matchers/optional_matcher.rb

@@ -7,6 +7,7 @@ module Shoulda
           attr_reader :missing_option
 
           def initialize(attribute_name, optional)
+            @attribute_name = attribute_name
             @optional = optional
             @submatcher = ActiveModel::AllowValueMatcher.new(nil).
               for(attribute_name)
@@ -21,16 +22,38 @@ module Shoulda
             if submatcher_passes?(subject)
               true
             else
-              @missing_option =
-                'the association should have been defined ' +
-                "with `optional: #{optional}`, but was not"
+              @missing_option = 'and for the record '
+
+              missing_option <<
+                if optional
+                  'not to '
+                else
+                  'to '
+                end
+
+              missing_option << (
+                'fail validation if ' +
+                ":#{attribute_name} is unset; i.e., either the association " +
+                'should have been defined with `optional: ' +
+                "#{optional.inspect}`, or there "
+              )
+
+              missing_option <<
+                if optional
+                  'should not '
+                else
+                  'should '
+                end
+
+              missing_option << "be a presence validation on :#{attribute_name}"
+
               false
             end
           end
 
           private
 
-          attr_reader :optional, :submatcher
+          attr_reader :attribute_name, :optional, :submatcher
 
           def submatcher_passes?(subject)
             if optional

data/lib/shoulda/matchers/active_record/association_matchers/required_matcher.rb

@@ -7,6 +7,7 @@ module Shoulda
           attr_reader :missing_option
 
           def initialize(attribute_name, required)
+            @attribute_name = attribute_name
             @required = required
             @submatcher = ActiveModel::DisallowValueMatcher.new(nil).
               for(attribute_name).
@@ -22,16 +23,38 @@ module Shoulda
             if submatcher_passes?(subject)
               true
             else
-              @missing_option =
-                'the association should have been defined ' +
-                "with `required: #{required}`, but was not"
+              @missing_option = 'and for the record '
+
+              missing_option <<
+                if required
+                  'to '
+                else
+                  'not to '
+                end
+
+              missing_option << (
+                'fail validation if ' +
+                ":#{attribute_name} is unset; i.e., either the association " +
+                'should have been defined with `required: ' +
+                "#{required.inspect}`, or there "
+              )
+
+              missing_option <<
+                if required
+                  'should '
+                else
+                  'should not '
+                end
+
+              missing_option << "be a presence validation on :#{attribute_name}"
+
               false
             end
           end
 
           private
 
-          attr_reader :required, :submatcher
+          attr_reader :attribute_name, :required, :submatcher
 
           def submatcher_passes?(subject)
             if required

data/lib/shoulda/matchers/active_record/validate_uniqueness_of_matcher.rb

@@ -144,7 +144,7 @@ module Shoulda
       # unique, but the scoped attributes are not unique either.
       #
       #     class Post < ActiveRecord::Base
-      #       validates :slug, uniqueness: true, scope: :journal_id
+      #       validates :slug, uniqueness: { scope: :journal_id }
       #     end
       #
       #     # RSpec

data/lib/shoulda/matchers/independent.rb

@@ -4,7 +4,8 @@ require 'shoulda/matchers/independent/delegate_method_matcher/target_not_defined
 
 module Shoulda
   module Matchers
-    # Matchers for non-Rails-dependent code.
+    # This module provides matchers that are used to test behavior outside of
+    # Rails-specific classes.
     module Independent
     end
   end

data/lib/shoulda/matchers/rails_shim.rb

@@ -128,20 +128,16 @@ module Shoulda
           options
         )
           default_translation_keys = [
+            :"activemodel.errors.models.#{model_name}.attributes.#{attribute}.#{type}",
+            :"activemodel.errors.models.#{model_name}.#{type}",
+            :"activemodel.errors.messages.#{type}",
+            :"activerecord.errors.models.#{model_name}.attributes.#{attribute}.#{type}",
             :"activerecord.errors.models.#{model_name}.#{type}",
             :"activerecord.errors.messages.#{type}",
             :"errors.attributes.#{attribute}.#{type}",
             :"errors.messages.#{type}",
           ]
-          primary_translation_key = [
-            :activerecord,
-            :errors,
-            :models,
-            model_name,
-            :attributes,
-            attribute,
-            type,
-          ]
+          primary_translation_key = default_translation_keys.shift
           translate_options =
             { default: default_translation_keys }.merge(options)
           I18n.translate(primary_translation_key, translate_options)