rspec-expectations 3.12.3 → 3.13.5

data/README.md

@@ -13,7 +13,9 @@ If you want to use rspec-expectations with rspec, just install the rspec gem
 and RubyGems will also install rspec-expectations for you (along with
 rspec-core and rspec-mocks):
 
-    gem install rspec
+```shell
+gem install rspec
+```
 
 Want to run against the `main` branch? You'll need to include the dependent
 RSpec repos as well. Add the following to your `Gemfile`:
@@ -27,7 +29,9 @@ end
 If you want to use rspec-expectations with another tool, like Test::Unit,
 Minitest, or Cucumber, you can install it directly:
 
-    gem install rspec-expectations
+```shell
+gem install rspec-expectations
+```
 
 ## Contributing
 
@@ -67,8 +71,10 @@ The `describe` and `it` methods come from rspec-core.  The `Order`, `LineItem`,
 expresses an expected outcome. If `order.total == Money.new(5.55, :USD)`, then
 the example passes. If not, it fails with a message like:
 
-    expected: #<Money @value=5.55 @currency=:USD>
-         got: #<Money @value=1.11 @currency=:USD>
+```
+  expected: #<Money @value=5.55 @currency=:USD>
+       got: #<Money @value=1.11 @currency=:USD>
+```
 
 ## Built-in matchers
 

data/lib/rspec/expectations/block_snippet_extractor.rb

@@ -46,11 +46,13 @@ module RSpec
           RSpec.world.source_from_file(file_path)
         end
       else
+        # :nocov:
         RSpec::Support.require_rspec_support 'source'
         def source
           raise TargetNotFoundError unless File.exist?(file_path)
           @source ||= RSpec::Support::Source.from_file(file_path)
         end
+        # :nocov:
       end
 
       def file_path

data/lib/rspec/expectations/configuration.rb

@@ -89,6 +89,7 @@ module RSpec
           ::RSpec.configuration.color_enabled?
         end
       else
+        # :nocov:
         # Indicates whether or not diffs should be colored.
         # Delegates to rspec-core's color option if rspec-core
         # is loaded; otherwise you can set it here.
@@ -100,8 +101,11 @@ module RSpec
         def color?
           defined?(@color) && @color
         end
+        # :nocov:
       end
 
+      # :nocov: Because this is only really _useful_ on 1.8, and hard to test elsewhere.
+      #
       # Adds `should` and `should_not` to the given classes
       # or modules. This can be used to ensure `should` works
       # properly on things like proxy objects (particular
@@ -114,6 +118,7 @@ module RSpec
           Expectations::Syntax.enable_should(mod)
         end
       end
+      # :nocov:
 
       # Sets or gets the backtrace formatter. The backtrace formatter should
       # implement `#format_backtrace(Array<String>)`. This is used
@@ -174,11 +179,18 @@ module RSpec
           # no-op, handler is something else
         end
       end
+
+      # Configures what RSpec will do about matcher use which would potentially cause
+      # false positives in tests. Defaults to `:warn` since this is generally the desired behavior,
+      # but can also be set to `:raise` or `:nothing`.
       #
-      # Configures what RSpec will do about matcher use which will
-      # potentially cause false positives in tests.
-      #
-      # @param [Symbol] behavior can be set to :warn, :raise or :nothing
+      # @overload on_potential_false_positives
+      #   @return [Symbol] the behavior setting
+      # @overload on_potential_false_positives=(value)
+      #   @param [Symbol] behavior can be set to `:warn`, `:raise` or `:nothing`
+      #   @return [Symbol] the behavior setting
+      attr_reader :on_potential_false_positives
+
       def on_potential_false_positives=(behavior)
         unless FALSE_POSITIVE_BEHAVIOURS.key?(behavior)
           raise ArgumentError, "Supported values are: #{FALSE_POSITIVE_BEHAVIOURS.keys}"
@@ -189,22 +201,24 @@ module RSpec
       # 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
-
+      #
+      # @overload strict_predicate_matchers
+      #   @return [Boolean]
+      # @overload strict_predicate_matchers?
+      #   @return [Boolean]
+      # @overload strict_predicate_matchers=(value)
+      #   @param [Boolean] value
       attr_reader :strict_predicate_matchers
 
+      def strict_predicate_matchers=(value)
+        raise ArgumentError, "Pass `true` or `false`" unless value == true || value == false
+        @strict_predicate_matchers = value
+      end
+
       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`.
-      attr_reader :on_potential_false_positives
-
       # Indicates whether RSpec will warn 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/fail_with.rb

@@ -30,7 +30,7 @@ module RSpec
                                "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        message = ::RSpec::Matchers::ExpectedsForMultipleDiffs.from(expected).message_with_diff(message, differ, actual)
+        message = ::RSpec::Matchers::MultiMatcherDiff.from(expected, actual).message_with_diff(message, differ)
 
         RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
       end

data/lib/rspec/expectations/failure_aggregator.rb

@@ -6,6 +6,10 @@ module RSpec
 
       # @private
       class AggregatedFailure
+        # :nocov:
+        # `inspect` was apparently used by some versions early in ruby 3 while constructing
+        # NoMethodError, but seems to be no longer.
+        #
         # @private
         MESSAGE =
           'AggregatedFailure: This method caused a failure which has been ' \
@@ -15,6 +19,7 @@ module RSpec
         def inspect
           MESSAGE
         end
+        # :nocov:
       end
 
       AGGREGATED_FAILURE = AggregatedFailure.new
@@ -75,11 +80,13 @@ module RSpec
         # 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.
+        # :nocov:
         def assign_backtrace(failure)
           raise failure
         rescue failure.class => e
           failure.set_backtrace(e.backtrace)
         end
+        # :nocov:
       else
         # Using `caller` performs better (and is simpler) than `raise` on most Rubies.
         def assign_backtrace(failure)

data/lib/rspec/expectations/handler.rb

@@ -4,11 +4,10 @@ module RSpec
     module ExpectationHelper
       def self.check_message(msg)
         unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
-          ::Kernel.warn [
-            "WARNING: ignoring the provided expectation message argument (",
-            msg.inspect,
-            ") since it is not a string or a proc."
-          ].join
+          RSpec.warning(
+            "ignoring the provided expectation message argument" \
+            "(#{ msg.inspect }) since it is not a string or a proc"
+          )
         end
       end
 

data/lib/rspec/expectations/version.rb

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

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

@@ -124,24 +124,6 @@ module RSpec
         end
         private_class_method :underscore
 
-      private
-
-        def assert_ivars(*expected_ivars)
-          return unless (expected_ivars - present_ivars).any?
-          ivar_list = EnglishPhrasing.list(expected_ivars)
-          raise "#{self.class.name} needs to supply#{ivar_list}"
-        end
-
-        if RUBY_VERSION.to_f < 1.9
-          # :nocov:
-          def present_ivars
-            instance_variables.map(&:to_sym)
-          end
-          # :nocov:
-        else
-          alias present_ivars instance_variables
-        end
-
         # @private
         module HashFormatting
           # `{ :a => 5, :b => 2 }.inspect` produces:
@@ -161,6 +143,51 @@ module RSpec
 
         include HashFormatting
 
+        # @private
+        module StringEncodingFormatting
+          # @api private
+          # @return [Boolean] True if the actual and expected string encoding are different.
+          #   i.e. the failure may be related to encoding differences and the encoding
+          #   should be shown to the user. false otherwise.
+          if String.method_defined?(:encoding)
+            def string_encoding_differs?
+              actual.is_a?(String) && expected.is_a?(String) && actual.encoding != expected.encoding
+            end
+          else
+            # @api private
+            # @return [Boolean] False always as the curent Ruby version does not support String encoding
+            # :nocov:
+            def string_encoding_differs?
+              false
+            end
+            # :nocov:
+          end
+          module_function :string_encoding_differs?
+
+          if String.method_defined?(:encoding)
+            # @api private
+            # Formats a String's encoding as a human readable string
+            # @param value [String]
+            # @return [String]
+            def format_encoding(value)
+              "#<Encoding:#{value.encoding.name}>"
+            end
+          else
+            # @api private
+            # Formats a String's encoding as a human readable string
+            # @param _value [String]
+            # @return [nil] nil as the curent Ruby version does not support String encoding
+            # :nocov:
+            def format_encoding(_value)
+              nil
+            end
+            # :nocov:
+          end
+          module_function :format_encoding
+        end
+
+        include StringEncodingFormatting
+
         # @api private
         # Provides default implementations of failure messages, based on the `description`.
         module DefaultFailureMessages

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

@@ -440,9 +440,11 @@ module RSpec
             Expectations::BlockSnippetExtractor.try_extracting_single_line_body_of(@value_proc, @matcher_name)
           end
         else
+          # :nocov:
           def extract_value_block_snippet
             nil
           end
+          # :nocov:
         end
       end
     end

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

@@ -51,10 +51,10 @@ module RSpec
         end
 
         # @api private
-        # @return [RSpec::Matchers::ExpectedsForMultipleDiffs]
+        # @return [RSpec::Matchers::MultiMatcherDiff]
         def expected
           return nil unless evaluator
-          ::RSpec::Matchers::ExpectedsForMultipleDiffs.for_many_matchers(diffable_matcher_list)
+          ::RSpec::Matchers::MultiMatcherDiff.for_many_matchers(diffable_matcher_list)
         end
 
       protected
@@ -77,8 +77,11 @@ module RSpec
         def match(_expected, actual)
           evaluator_klass = if supports_block_expectations? && Proc === actual
                               NestedEvaluator
-                            else
+                            elsif supports_value_expectations?
                               SequentialEvaluator
+                            else
+                              # Can't raise an ArgumentError in this context, as it's rescued
+                              raise "Block and value matchers can't be combined in a compound expectation (#{matcher_1.description}, #{matcher_2.description})"
                             end
 
           @evaluator = evaluator_klass.new(actual, matcher_1, matcher_2)

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

@@ -108,12 +108,14 @@ module RSpec
         end
 
         if RUBY_VERSION == "1.8.7"
+          # :nocov:
           def to_a_disallowed?(object)
             case object
             when NilClass, String then true
             else Kernel == RSpec::Support.method_handle_for(object, :to_a).owner
             end
           end
+          # :nocov:
         else
           def to_a_disallowed?(object)
             NilClass === object

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

@@ -61,9 +61,11 @@ module RSpec
             count.cover?(number)
           end
         else
+          # :nocov:
           def cover?(count, number)
             number >= count.first && number <= count.last
           end
+          # :nocov:
         end
 
         def expected_count_matches?(actual_count)

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

@@ -8,7 +8,11 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message
-          "\nexpected: #{expected_formatted}\n     got: #{actual_formatted}\n\n(compared using ==)\n"
+          if string_encoding_differs?
+            "\nexpected: #{format_encoding(expected)} #{expected_formatted}\n     got: #{format_encoding(actual)} #{actual_formatted}\n\n(compared using ==)\n"
+          else
+            "\nexpected: #{expected_formatted}\n     got: #{actual_formatted}\n\n(compared using ==)\n"
+          end
         end
 
         # @api private

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

@@ -8,7 +8,11 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message
-          "\nexpected: #{expected_formatted}\n     got: #{actual_formatted}\n\n(compared using eql?)\n"
+          if string_encoding_differs?
+            "\nexpected: #{format_encoding(expected)} #{expected_formatted}\n     got: #{format_encoding(actual)} #{actual_formatted}\n\n(compared using eql?)\n"
+          else
+            "\nexpected: #{expected_formatted}\n     got: #{actual_formatted}\n\n(compared using eql?)\n"
+          end
         end
 
         # @api private

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

@@ -46,8 +46,27 @@ module RSpec
 
       private
 
+        # Catch a semi-frequent typo - if you have strict_predicate_matchers disabled and
+        # expect(spy).to have_receieveddd(:foo) it would be evergreen - the dynamic matcher
+        # queries `has_receiveddd?`, the spy _fakes_ the method, returning its (truthy) self.
+        if defined?(RSpec::Mocks::Double)
+          def really_responds_to?(method)
+            if RSpec::Mocks::Double === @actual
+              @actual.respond_to?(method) && methods_include?(method)
+            else
+              @actual.respond_to?(method)
+            end
+          end
+        else
+          # :nocov:
+          def really_responds_to?(method)
+            @actual.respond_to?(method)
+          end
+          # :nocov:
+        end
+
         def predicate_accessible?
-          @actual.respond_to? predicate
+          really_responds_to?(predicate)
         end
 
         # support 1.8.7, evaluate once at load time for performance
@@ -56,11 +75,19 @@ module RSpec
           def private_predicate?
             @actual.private_methods.include? predicate.to_s
           end
+
+          def methods_include?(method)
+            @actual.methods.include?(method.to_s)
+          end
           # :nocov:
         else
           def private_predicate?
             @actual.private_methods.include? predicate
           end
+
+          def methods_include?(method)
+            @actual.methods.include?(method)
+          end
         end
 
         def predicate_result
@@ -155,7 +182,7 @@ module RSpec
         end
 
         def predicate_accessible?
-          super || actual.respond_to?(present_tense_predicate)
+          super || really_responds_to?(present_tense_predicate)
         end
 
         def present_tense_predicate

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

@@ -13,6 +13,7 @@ module RSpec
 
         # @api private
         def initialize(*expecteds)
+          raise(ArgumentError, 'include() is not supported, please supply an argument') if expecteds.empty?
           @expecteds = expecteds
         end
 
@@ -165,6 +166,7 @@ module RSpec
         end
 
         def actual_collection_includes?(expected_item)
+          return actual.scan(expected_item).size > 0 if Regexp === expected_item && String === actual
           return true if actual.include?(expected_item)
 
           # String lacks an `any?` method...
@@ -174,9 +176,11 @@ module RSpec
         end
 
         if RUBY_VERSION < '1.9'
+          # :nocov:
           def count_enumerable(expected_item)
             actual.select { |value| values_match?(expected_item, value) }.size
           end
+          # :nocov:
         else
           def count_enumerable(expected_item)
             actual.count { |value| values_match?(expected_item, value) }
@@ -197,6 +201,7 @@ module RSpec
 
         def diff_would_wrongly_highlight_matched_item?
           return false unless actual.is_a?(String) && expected.is_a?(Array)
+          return false if Regexp === expecteds.first
 
           lines = actual.split("\n")
           expected.any? do |str|

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

@@ -33,11 +33,23 @@ module RSpec
           self
         end
 
+        # @api private
+        # @return [String]
+        def failure_message
+          if Array === expected && !(actual.respond_to?(:to_a) || actual.respond_to?(:to_ary))
+            return "expected a collection that can be converted to an array with " \
+                   "`#to_ary` or `#to_a`, but got #{actual_formatted}"
+          end
+
+          super
+        end
+
       private
 
         def match(expected, actual)
           return match_captures(expected, actual) if @expected_captures
           return true if values_match?(expected, actual)
+          return false if Array === expected
           return false unless can_safely_call_match?(expected, actual)
           actual.match(expected)
         end
@@ -78,9 +90,11 @@ module RSpec
           # @api private
           # Returns match data names for named captures
           # @return Array
+          # :nocov:
           def names
             []
           end
+          # :nocov:
         else
           # @api private
           # Returns match data names for named captures

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

@@ -13,6 +13,10 @@ module RSpec
         # argument. We can't use `nil` for that because we need to warn when `nil` is
         # passed in a different way. It's an Object, not a Module, since Module's `===`
         # does not evaluate to true when compared to itself.
+        #
+        # Note; this _is_ the default value supplied for expected_error_or_message, but
+        # because there are two method-calls involved, that default is actually supplied
+        # in the definition of the _matcher_ method, `RSpec::Matchers#raise_error`
         UndefinedValue = Object.new.freeze
 
         def initialize(expected_error_or_message, expected_message, &block)
@@ -25,7 +29,7 @@ module RSpec
           when nil, UndefinedValue
             @expected_error = Exception
             @expected_message = expected_message
-          when String
+          when String, Regexp
             @expected_error = Exception
             @expected_message = expected_error_or_message
           else

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

@@ -50,9 +50,11 @@ module RSpec
             Expectations::BlockSnippetExtractor.try_extracting_single_line_body_of(@block, matcher_name)
           end
         else
+          # :nocov:
           def block_representation
             'block'
           end
+          # :nocov:
         end
       end
     end

data/lib/rspec/matchers/dsl.rb

@@ -467,11 +467,12 @@ module RSpec
           @chained_method_clauses = []
           @block_arg = block_arg
 
-          klass = class << self
-            # See `Macros#define_user_override` above, for an explanation.
-            include(@user_method_defs = Module.new)
-            self
-          end
+          klass =
+            class << self
+              # See `Macros#define_user_override` above, for an explanation.
+              include(@user_method_defs = Module.new)
+              self
+            end
           RSpec::Support::WithKeywordsWhenNeeded.class_exec(klass, *expected, &declarations)
         end
 

data/lib/rspec/matchers/english_phrasing.rb

@@ -45,12 +45,14 @@ module RSpec
         # So here we replace `Kernel#Array` with our own warning-free implementation for 1.8.7.
         # @private
         # rubocop:disable Naming/MethodName
+        # :nocov:
         def self.Array(obj)
           case obj
           when Array then obj
           else [obj]
           end
         end
+        # :nocov:
         # rubocop:enable Naming/MethodName
       end
     end

data/lib/rspec/matchers/matcher_delegator.rb

@@ -1,8 +1,34 @@
 module RSpec
   module Matchers
+    # Provides a base class with as little methods as possible, so that
+    # most methods can be delegated via `method_missing`.
+    #
+    # On Ruby 2.0+ BasicObject could be used for this purpose, but it
+    # introduce some extra complexity with constant resolution, so the
+    # BlankSlate pattern was prefered.
+    # @private
+    class BaseDelegator
+      kept_methods = [
+        # Methods that raise warnings if removed.
+        :__id__, :__send__, :object_id,
+
+        # Methods that are explicitly undefined in some subclasses.
+        :==, :===,
+
+        # Methods we keep on purpose.
+        :class, :respond_to?, :__method__, :method, :dup,
+        :clone, :initialize_dup, :initialize_copy, :initialize_clone,
+      ]
+      instance_methods.each do |method|
+        unless kept_methods.include?(method.to_sym)
+          undef_method(method)
+        end
+      end
+    end
+
     # Provides the necessary plumbing to wrap a matcher with a decorator.
     # @private
-    class MatcherDelegator
+    class MatcherDelegator < BaseDelegator
       include Composable
       attr_reader :base_matcher