rspec-expectations 3.8.6 → 3.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f0c43e7a6933605f4b96eb0a5545bd5e1b03a2b2de4471edada5000f3c5c37
-  data.tar.gz: 62b85e7625d066114174dfaa586dbb2cb419aa0bc470b68918c2524b841f8762
+  metadata.gz: f0b59eb5a0bf0dcaf99ae45b411fa1d8e73a3cf5b0694f06170205ff36b22bc1
+  data.tar.gz: 91f0f17601c3853d8e10219dfb2c41a53fba78b4d3c546870ebe1fac9de70a6b
 SHA512:
-  metadata.gz: 5ba237ec4317b7af0780f5e929e10da26b501f76a23cb807684498a21118ef0f72598c1ded7ee0436a8a29f97ea16a0d4f887c7b345b22302f5b8ef50c660beb
-  data.tar.gz: 4138b8b208b668216660d55f5634440e8240c4a36f15489fc3e1e6093d4a8530fc419d9f958ea4526ac63e7e9e2d589c7716a21832d257adac823486d5dfae77
+  metadata.gz: 99e2aff242508b307566d95120c66e507cde5da5e6aec973365b747e1b16fde3ab34445ce2cfddf153baeac2c3f75c05b1e0f105465118544aad8fb9dafbe37e
+  data.tar.gz: c69b2d96fc2c3abec310e9e36b346cc3a1017a160906c795b1218b1e1a2dbea10055a80fc89da6510c89eb9cc7ef82e7f24c63ff2893f3c692a008de0ec838f1

data/Changelog.md

@@ -1,3 +1,149 @@
+### Development
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.12.1...3-12-maintenance)
+
+### 3.12.2 / 2023-01-07
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.12.1...v3.12.2)
+
+Bug Fixes:
+
+* Prevent deprecation warning when using the `exist` matcher with `Dir`.
+  (Steve Dierker, #1398)
+
+### 3.12.1 / 2022-12-16
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.12.0...v3.12.1)
+
+Bug Fixes:
+
+* Pass keyword arguments through to aliased (and thus negated) matchers. (Jon Rowe, #1394)
+* When handling failures in an aggregated_failures block (or example) prevent
+  the failure list leaking out. (Maciek Rząsa, #1392)
+
+### 3.12.0 / 2022-10-26
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.11.1...v3.12.0)
+
+Enhancements:
+
+* Add `an_array_matching` alias for `match_array` to improve readability as an argument
+  matcher. (Mark Schneider, #1361)
+
+### 3.11.1 / 2022-09-12
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.11.0...v3.11.1)
+
+Bug Fixes:
+
+* Allow the `contain_exactly` matcher to be reused by resetting its
+  internals on `matches?` (@bclayman-sq, #1326)
+* Using the exist matcher on `FileTest` no longer produces a deprecation warning.
+  (Ryo Nakamura, #1383)
+
+### 3.11.0 / 2022-02-09
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.10.2...v3.11.0)
+
+Enhancements:
+
+* Return `true` from `aggregate_failures` when no exception occurs. (Jon Rowe, #1225)
+
+Deprecations:
+
+* Print a deprecation message when using the implicit block expectation syntax.
+  (Phil Pirozhkov, #1139)
+
+### 3.10.2 / 2022-01-14
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.10.1...v3.10.2)
+
+Bug Fixes:
+
+* Fix support for dynamic matchers for expectation target checks (Phil Pirozhkov, #1294)
+* Fix `expect(array).to include(hash).times`, previously this would fail due to
+  matching the entire array as a single hash, rather than a member of the hash.
+  (Slava Kardakov, #1322)
+* Ensure `raise_error` matches works with the `error_highlight` option from Ruby 3.1.
+  (Peter Goldstein, #1339)
+
+### 3.10.1 / 2020-12-27
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.10.0...v3.10.1)
+
+Bug Fixes:
+
+* Allow JRuby 9.2.x.x to generate backtraces normally rather than via our
+  backfill workaround. (#1230, Jon Rowe)
+
+### 3.10.0 / 2020-10-30
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.9.3...v3.10.0)
+
+Enhancements:
+
+* Allow `include` matcher to be chained with `once`, `at_least`, etc. for simple cases.
+  (Marc-André Lafortune, #1168)
+* Add an explicit warning when `nil` is passed to `raise_error`. (Phil Pirozhkov, #1143)
+* Improve `include` matcher's composability. (Phil Pirozhkov, #1155)
+* Mocks expectations can now set a custom failure message.
+  (Benoit Tigeot and Nicolas Zermati, #1156)
+* `aggregate_failures` now shows the backtrace line for each failure. (Fabricio Bedin, #1163)
+* Support multiple combinations of `yield_control` modifiers like `at_least`, `at_most`.
+  (Jon Rowe, #1169)
+* Dynamic `have_<n>` matchers now have output consistent with other dynamic matchers.
+  (Marc-André Lafortune, #1195)
+* New config option `strict_predicate_matchers` allows predicate matcher to be strict
+  (i.e. match for `true` or `false`) instead of the default (match truthy vs `false` or `nil`).
+  (Marc-André Lafortune, #1196)
+
+### 3.9.4 / 2020-10-29
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.9.3...v3.9.4)
+
+Bug Fixes:
+
+* Fix regression with `be_` and `have_` matchers and arguments implementing `to_hash`
+  were they would act like keywords and be cast to a hash. (Jon Rowe, #1222)
+
+### 3.9.3 / 2020-10-23
+
+Bug Fixes:
+
+* Swap the comparison of the delta vs the expected for the `be_within` matcher allowing
+  more complicated oobjects to be compared providing they provide `abs` and other
+  comparison methods. (Kelly Stannard, #1182)
+* Properly format expected in the description of the `be_within` matcher. (Jon Rowe, #1185)
+* Remove warning when using keyword arguments with `be_` and `have_` matchers on 2.7.x
+  (Jon Rowe, #1187)
+* Prevent formatting a single hash as a list of key value pairs in default failure messages
+  for custom matches (fixes formatting in `EnglishPhrasing#list`). (Robert Eshleman, #1193)
+* Prevent errors from causing false positives when using `be <operator>` comparison, e.g.
+  `expect(1).not_to be < 'a'` will now correctly fail rather than pass. (Jon Rowe, #1208)
+
+
+### 3.9.2 / 2020-05-08
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.9.1...v3.9.2)
+
+Bug Fixes:
+
+* Issue a proper `ArgumentError` when invalid arguments are given to `yield_control`
+  modifiers such as `at_least` et al. (Marc-André Lafortune, #1167)
+* Prevent Ruby 2.7 keyword arguments warning from being issued by custom
+  matcher definitions. (Jon Rowe, #1176)
+
+### 3.9.1 / 2020-03-13
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.9.0...v3.9.1)
+
+Bug Fixes:
+
+* Issue an improved warning when using `respond_to(...).with(n).arguments` and ignore
+  the warning when using with `have_attributes(...)`. (Jon Rowe, #1164)
+
+### 3.9.0 / 2019-10-08
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.8.6...v3.9.0)
+
+Enhancements:
+
+* The `respond_to` matcher now uses the signature from `initialize` to validate checks
+  for `new` (unless `new` is non standard). (Jon Rowe, #1072)
+* Generated descriptions for matchers now use `is expected to` rather than `should` in
+  line with our preferred DSL. (Pete Johns, #1080, rspec/rspec-core#2572)
+* Add the ability to re-raise expectation errors when matching
+  with `match_when_negated` blocks. (Jon Rowe, #1130)
+* Add a warning when an empty diff is produce due to identical inspect output.
+  (Benoit Tigeot, #1126)
+
 ### 3.8.6 / 2019-10-07
 
 Bug Fixes:
@@ -29,7 +175,7 @@ Bug Fixes:
 * Prevent composed `all` matchers from leaking into their siblings leading to duplicate
   failures. (Jamie English, #1086)
 * Prevent objects which change their hash on comparison from failing change checks.
-  (Phil Pirozhkov, #1110)
+  (Phil Pirozhkov, #1100)
 * Issue an `ArgumentError` rather than a `NoMethodError` when `be_an_instance_of` and
   `be_kind_of` matchers encounter objects not supporting those methods.
   (Taichi Ishitani, #1107)

data/README.md

@@ -1,4 +1,4 @@
-# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.svg?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![Code Climate](https://codeclimate.com/github/rspec/rspec-expectations.svg)](https://codeclimate.com/github/rspec/rspec-expectations)
+# RSpec Expectations [![Build Status](https://github.com/rspec/rspec-expectations/workflows/RSpec%20CI/badge.svg)](https://github.com/rspec/rspec-expectations/actions) [![Code Climate](https://codeclimate.com/github/rspec/rspec-expectations.svg)](https://codeclimate.com/github/rspec/rspec-expectations)
 
 RSpec::Expectations lets you express expected outcomes on an object in an
 example.
@@ -15,12 +15,12 @@ rspec-core and rspec-mocks):
 
     gem install rspec
 
-Want to run against the `master` branch? You'll need to include the dependent
+Want to run against the `main` branch? You'll need to include the dependent
 RSpec repos as well. Add the following to your `Gemfile`:
 
 ```ruby
 %w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
-  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'master'
+  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'main'
 end
 ```
 
@@ -175,30 +175,45 @@ expect(1..10).to cover(3)
 ### Collection membership
 
 ```ruby
-expect(actual).to include(expected)
+# exact order, entire collection
+expect(actual).to eq(expected)
+
+# exact order, partial collection (based on an exact position)
 expect(actual).to start_with(expected)
 expect(actual).to end_with(expected)
 
-expect(actual).to contain_exactly(individual, items)
-# ...which is the same as:
-expect(actual).to match_array(expected_array)
+# any order, entire collection
+expect(actual).to match_array(expected)
+
+# You can also express this by passing the expected elements
+# as individual arguments
+expect(actual).to contain_exactly(expected_element1, expected_element2)
+
+ # any order, partial collection
+expect(actual).to include(expected)
 ```
 
 #### Examples
 
 ```ruby
-expect([1, 2, 3]).to include(1)
-expect([1, 2, 3]).to include(1, 2)
-expect([1, 2, 3]).to start_with(1)
-expect([1, 2, 3]).to start_with(1, 2)
-expect([1, 2, 3]).to end_with(3)
-expect([1, 2, 3]).to end_with(2, 3)
-expect({:a => 'b'}).to include(:a => 'b')
-expect("this string").to include("is str")
-expect("this string").to start_with("this")
-expect("this string").to end_with("ring")
-expect([1, 2, 3]).to contain_exactly(2, 3, 1)
-expect([1, 2, 3]).to match_array([3, 2, 1])
+expect([1, 2, 3]).to eq([1, 2, 3])            # Order dependent equality check
+expect([1, 2, 3]).to include(1)               # Exact ordering, partial collection matches
+expect([1, 2, 3]).to include(2, 3)            #
+expect([1, 2, 3]).to start_with(1)            # As above, but from the start of the collection
+expect([1, 2, 3]).to start_with(1, 2)         #
+expect([1, 2, 3]).to end_with(3)              # As above but from the end of the collection
+expect([1, 2, 3]).to end_with(2, 3)           #
+expect({:a => 'b'}).to include(:a => 'b')     # Matching within hashes
+expect("this string").to include("is str")    # Matching within strings
+expect("this string").to start_with("this")   #
+expect("this string").to end_with("ring")     #
+expect([1, 2, 3]).to contain_exactly(2, 3, 1) # Order independent matches
+expect([1, 2, 3]).to match_array([3, 2, 1])   #
+
+# Order dependent compound matchers
+expect(
+  [{:a => 'hash'},{:a => 'another'}]
+).to match([a_hash_including(:a => 'hash'), a_hash_including(:a => 'another')])
 ```
 
 ## `should` syntax
@@ -212,7 +227,7 @@ actual.should be > 3
 [1, 2, 3].should_not include 4
 ```
 
-See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/master/Should.md)
+See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/main/Should.md)
 
 ## Compound Matcher Expressions
 

data/lib/rspec/expectations/configuration.rb

@@ -28,6 +28,7 @@ module RSpec
 
       def initialize
         @on_potential_false_positives = :warn
+        @strict_predicate_matchers = false
       end
 
       # Configures the supported syntax.
@@ -185,6 +186,20 @@ module RSpec
         @on_potential_false_positives = behavior
       end
 
+      # Configures RSpec to check predicate matchers to `be(true)` / `be(false)` (strict),
+      # or `be_truthy` / `be_falsey` (not strict).
+      # Historically, the default was `false`, but `true` is recommended.
+      def strict_predicate_matchers=(flag)
+        raise ArgumentError, "Pass `true` or `false`" unless flag == true || flag == false
+        @strict_predicate_matchers = flag
+      end
+
+      attr_reader :strict_predicate_matchers
+
+      def strict_predicate_matchers?
+        @strict_predicate_matchers
+      end
+
       # Indicates what RSpec will do about matcher use which will
       # potentially cause false positives in tests, generally you want to
       # avoid such scenarios so this defaults to `true`.

data/lib/rspec/expectations/expectation_target.rb

@@ -42,7 +42,7 @@ module RSpec
         elsif block
           raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
         else
-          new(value)
+          ValueExpectationTarget.new(value)
         end
       end
 
@@ -57,7 +57,7 @@ module RSpec
         #   expect { perform }.to raise_error
         # @param [Matcher]
         #   matcher
-        # @param [String or Proc] message optional message to display when the expectation fails
+        # @param [String, Proc] message optional message to display when the expectation fails
         # @return [Boolean] true if the expectation succeeds (else raises)
         # @see RSpec::Matchers
         def to(matcher=nil, message=nil, &block)
@@ -70,7 +70,7 @@ module RSpec
         #   expect(value).not_to eq(5)
         # @param [Matcher]
         #   matcher
-        # @param [String or Proc] message optional message to display when the expectation fails
+        # @param [String, Proc] message optional message to display when the expectation fails
         # @return [Boolean] false if the negative expectation succeeds (else raises)
         # @see RSpec::Matchers
         def not_to(matcher=nil, message=nil, &block)
@@ -90,6 +90,44 @@ module RSpec
       include InstanceMethods
     end
 
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # expectations, in order to avoid user confusion when they
+    # use a block thinking the expectation will be on the return
+    # value of the block rather than the block itself.
+    class ValueExpectationTarget < ExpectationTarget
+      def to(matcher=nil, message=nil, &block)
+        enforce_value_expectation(matcher)
+        super
+      end
+
+      def not_to(matcher=nil, message=nil, &block)
+        enforce_value_expectation(matcher)
+        super
+      end
+
+    private
+
+      def enforce_value_expectation(matcher)
+        return if supports_value_expectations?(matcher)
+
+        RSpec.deprecate(
+          "expect(value).to #{RSpec::Support::ObjectFormatter.format(matcher)}",
+          :message =>
+            "The implicit block expectation syntax is deprecated, you should pass " \
+            "a block rather than an argument to `expect` to use the provided " \
+            "block expectation matcher or the matcher must implement " \
+            "`supports_value_expectations?`. e.g  `expect { value }.to " \
+            "#{RSpec::Support::ObjectFormatter.format(matcher)}` not " \
+            "`expect(value).to #{RSpec::Support::ObjectFormatter.format(matcher)}`"
+        )
+      end
+
+      def supports_value_expectations?(matcher)
+        !matcher.respond_to?(:supports_value_expectations?) || matcher.supports_value_expectations?
+      end
+    end
+
     # @private
     # Validates the provided matcher to ensure it supports block
     # expectations, in order to avoid user confusion when they
@@ -118,9 +156,7 @@ module RSpec
       end
 
       def supports_block_expectations?(matcher)
-        matcher.supports_block_expectations?
-      rescue NoMethodError
-        false
+        matcher.respond_to?(:supports_block_expectations?) && matcher.supports_block_expectations?
       end
     end
   end

data/lib/rspec/expectations/failure_aggregator.rb

@@ -4,6 +4,21 @@ module RSpec
     class FailureAggregator
       attr_reader :block_label, :metadata
 
+      # @private
+      class AggregatedFailure
+        # @private
+        MESSAGE =
+          'AggregatedFailure: This method caused a failure which has been ' \
+          'suppressed to be aggregated into our failure report by returning ' \
+          'this value, further errors can be ignored.'
+
+        def inspect
+          MESSAGE
+        end
+      end
+
+      AGGREGATED_FAILURE = AggregatedFailure.new
+
       def aggregate
         RSpec::Support.with_failure_notifier(self) do
           begin
@@ -48,14 +63,16 @@ module RSpec
         @seen_source_ids[source_id] = true
         assign_backtrace(failure) unless failure.backtrace
         failures << failure
+
+        AGGREGATED_FAILURE
       end
 
     private
 
-      if RSpec::Support::Ruby.jruby?
-        # On JRuby, `caller` and `raise` produce different backtraces with regards to `.java`
-        # stack frames. It's important that we use `raise` for JRuby to produce a backtrace
-        # that has a continuous common section with the raised `MultipleExpectationsNotMetError`,
+      if RSpec::Support::Ruby.jruby? && RSpec::Support::Ruby.jruby_version < '9.2.0.0'
+        # On JRuby 9.1.x.x and before, `caller` and `raise` produce different backtraces with
+        # regards to `.java` stack frames. It's important that we use `raise` for JRuby to produce
+        # a backtrace that has a continuous common section with the raised `MultipleExpectationsNotMetError`,
         # so that rspec-core's truncation logic can work properly on it to list the backtrace
         # relative to the `aggregate_failures` block.
         def assign_backtrace(failure)
@@ -80,7 +97,7 @@ module RSpec
         all_errors = failures + other_errors
 
         case all_errors.size
-        when 0 then return nil
+        when 0 then return true
         when 1 then RSpec::Support.notify_failure all_errors.first
         else RSpec::Support.notify_failure MultipleExpectationsNotMetError.new(self)
         end
@@ -150,11 +167,29 @@ module RSpec
       def enumerated(exceptions, index_offset)
         exceptions.each_with_index.map do |exception, index|
           index += index_offset
-          formatted_message = yield exception
+          formatted_message = "#{yield exception}\n#{format_backtrace(exception.backtrace).first}"
           "#{index_label index}#{indented formatted_message, index}"
         end
       end
 
+      def exclusion_patterns
+        patterns = %w[/lib\d*/ruby/ bin/ exe/rspec /lib/bundler/ /exe/bundle:]
+        patterns << "org/jruby/" if RSpec::Support::Ruby.jruby?
+        patterns.map! { |s| Regexp.new(s.gsub('/', File::SEPARATOR)) }
+      end
+
+      def format_backtrace(backtrace)
+        backtrace.map { |l| backtrace_line(l) }.compact.tap { |filtered| filtered.concat backtrace if filtered.empty? }
+      end
+
+      def backtrace_line(line)
+        return if [Regexp.union(RSpec::CallerFilter::IGNORE_REGEX, *exclusion_patterns)].any? { |p| line =~ p }
+
+        # It changes the current path that is relative to
+        # system root to be relative to the project root.
+        line.sub(/(\A|\s)#{File.expand_path('.')}(#{File::SEPARATOR}|\s|\Z)/, '\\1.\\2'.freeze).sub(/\A([^:]+:\d+)$/, '\\1'.freeze)
+      end
+
       def enumerated_failures
         enumerated(failures, 0, &:message)
       end

data/lib/rspec/expectations/handler.rb

@@ -44,15 +44,21 @@ module RSpec
 
     # @private
     class PositiveExpectationHandler
-      def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
+      def self.handle_matcher(actual, initial_matcher, custom_message=nil, &block)
+        ExpectationHelper.with_matcher(self, initial_matcher, custom_message) do |matcher|
           return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
-          matcher.matches?(actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message)
+
+          match_result = matcher.matches?(actual, &block)
+          if custom_message && match_result.respond_to?(:error_generator)
+            match_result.error_generator.opts[:message] = custom_message
+          end
+
+          match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message)
         end
       end
 
       def self.verb
-        "should"
+        'is expected to'
       end
 
       def self.should_method
@@ -66,10 +72,16 @@ module RSpec
 
     # @private
     class NegativeExpectationHandler
-      def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
+      def self.handle_matcher(actual, initial_matcher, custom_message=nil, &block)
+        ExpectationHelper.with_matcher(self, initial_matcher, custom_message) do |matcher|
           return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
-          does_not_match?(matcher, actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated)
+
+          negated_match_result = does_not_match?(matcher, actual, &block)
+          if custom_message && negated_match_result.respond_to?(:error_generator)
+            negated_match_result.error_generator.opts[:message] = custom_message
+          end
+
+          negated_match_result || ExpectationHelper.handle_failure(matcher, custom_message, :failure_message_when_negated)
         end
       end
 
@@ -82,7 +94,7 @@ module RSpec
       end
 
       def self.verb
-        "should not"
+        'is expected not to'
       end
 
       def self.should_method

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.8.6'
+      STRING = '3.12.2'
     end
   end
 end

data/lib/rspec/matchers/aliased_matcher.rb

@@ -99,14 +99,14 @@ module RSpec
       # by going through the effort of defining a negated matcher.
       #
       # However, if the override didn't actually change anything, then we
-      # should return the opposite failure message instead -- the overriden
+      # should return the opposite failure message instead -- the overridden
       # message is going to be confusing if we return it as-is, as it represents
       # the non-negated failure message for a negated match (or vice versa).
       def optimal_failure_message(same, inverted)
         if DefaultFailureMessages.has_default_failure_messages?(@base_matcher)
           base_message = @base_matcher.__send__(same)
-          overriden    = @description_block.call(base_message)
-          return overriden if overriden != base_message
+          overridden    = @description_block.call(base_message)
+          return overridden if overridden != base_message
         end
 
         @base_matcher.__send__(inverted)

data/lib/rspec/matchers/built_in/base_matcher.rb

@@ -78,6 +78,11 @@ module RSpec
           false
         end
 
+        # @private
+        def supports_value_expectations?
+          true
+        end
+
         # @api private
         def expects_call_stack_jump?
           false