mocha 2.1.0 → 2.7.1

data/lib/mocha/expectation.rb

@@ -193,6 +193,11 @@ module Mocha
     #
     # May be used with Ruby literals or variables for exact matching or with parameter matchers for less-specific matching, e.g. {ParameterMatchers#includes}, {ParameterMatchers#has_key}, etc. See {ParameterMatchers} for a list of all available parameter matchers.
     #
+    # Alternatively a block argument can be passed to {#with} to implement custom parameter matching. The block receives the +*actual_parameters+ as its arguments and should return +true+ if they are acceptable or +false+ otherwise. See the example below where a method is expected to be called with a value divisible by 4.
+    # The block argument takes precedence over +expected_parameters_or_matchers+. The block may be called multiple times per invocation of the expected method and so it should be idempotent.
+    #
+    # Note that if {#with} is called multiple times on the same expectation, the last call takes precedence; other calls are ignored.
+    #
     # Positional arguments were separated from keyword arguments in Ruby v3 (see {https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0 this article}). In relation to this a new configuration option ({Configuration#strict_keyword_argument_matching=}) is available in Ruby >= 2.7.
     #
     # When {Configuration#strict_keyword_argument_matching=} is set to +false+ (which is currently the default), a positional +Hash+ and a set of keyword arguments passed to {#with} are treated the same for the purposes of parameter matching. However, a deprecation warning will be displayed if a positional +Hash+ matches a set of keyword arguments or vice versa. This is because {Configuration#strict_keyword_argument_matching=} will default to +true+ in the future.
@@ -202,10 +207,10 @@ module Mocha
     # @see ParameterMatchers
     # @see Configuration#strict_keyword_argument_matching=
     #
-    # @param [*Array<Object,ParameterMatchers::Base>] expected_parameters_or_matchers expected parameter values or parameter matchers.
+    # @param [Array<Object,ParameterMatchers::Base>] expected_parameters_or_matchers expected parameter values or parameter matchers.
     # @yield optional block specifying custom matching.
-    # @yieldparam [*Array<Object>] actual_parameters parameters with which expected method was invoked.
-    # @yieldreturn [Boolean] +true+ if +actual_parameters+ are acceptable.
+    # @yieldparam [Array<Object>] actual_parameters parameters with which expected method was invoked.
+    # @yieldreturn [Boolean] +true+ if +actual_parameters+ are acceptable; +false+ otherwise.
     # @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
     #
     # @example Expected method must be called with exact parameter values.
@@ -256,7 +261,7 @@ module Mocha
     #   example.foo('a', { bar: 'b' })
     #   # This now fails as expected
     #
-    # @example Expected method must be called with a value divisible by 4.
+    # @example Using a block argument to expect the method to be called with a value divisible by 4.
     #   object = mock()
     #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
     #   object.expected_method(16)
@@ -266,6 +271,22 @@ module Mocha
     #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
     #   object.expected_method(17)
     #   # => verify fails
+    #
+    # @example Extracting a custom matcher into an instance method on the test class.
+    #   class MyTest < Minitest::Test
+    #     def test_expected_method_is_called_with_a_value_divisible_by_4
+    #       object = mock()
+    #       object.expects(:expected_method).with(&method(:divisible_by_4))
+    #       object.expected_method(16)
+    #       # => verify succeeds
+    #     end
+    #
+    #     private
+    #
+    #     def divisible_by_4(value)
+    #       value % 4 == 0
+    #     end
+    #   end
     def with(*expected_parameters_or_matchers, &matching_block)
       @parameters_matcher = ParametersMatcher.new(expected_parameters_or_matchers, self, &matching_block)
       self
@@ -632,14 +653,20 @@ module Mocha
       @ordering_constraints.all?(&:allows_invocation_now?)
     end
 
+    # @private
+    def ordering_constraints_not_allowing_invocation_now
+      @ordering_constraints.reject(&:allows_invocation_now?)
+    end
+
     # @private
     def matches_method?(method_name)
       @method_matcher.match?(method_name)
     end
 
     # @private
-    def match?(invocation)
-      @method_matcher.match?(invocation.method_name) && @parameters_matcher.match?(invocation.arguments) && @block_matcher.match?(invocation.block) && in_correct_order?
+    def match?(invocation, ignoring_order: false)
+      order_independent_match = @method_matcher.match?(invocation.method_name) && @parameters_matcher.match?(invocation.arguments) && @block_matcher.match?(invocation.block)
+      ignoring_order ? order_independent_match : order_independent_match && in_correct_order?
     end
 
     # @private
@@ -647,6 +674,11 @@ module Mocha
       @cardinality.invocations_allowed?
     end
 
+    # @private
+    def invocations_never_allowed?
+      @cardinality.invocations_never_allowed?
+    end
+
     # @private
     def satisfied?
       @cardinality.satisfied?

data/lib/mocha/expectation_error_factory.rb

@@ -6,9 +6,9 @@ module Mocha
   #
   # This class should only be used by authors of test libraries and not by typical "users" of Mocha.
   #
-  # For example, it is used by +Mocha::Integration::MiniTest::Adapter+ in order to have Mocha raise a +MiniTest::Assertion+ which can then be sensibly handled by +MiniTest::Unit::TestCase+.
+  # For example, it is used by +Mocha::Integration::Minitest::Adapter+ in order to have Mocha raise a +Minitest::Assertion+ which can then be sensibly handled by +Minitest::Unit::TestCase+.
   #
-  # @see Mocha::Integration::MiniTest::Adapter
+  # @see Mocha::Integration::Minitest::Adapter
   class ExpectationErrorFactory
     class << self
       # @!attribute exception_class

data/lib/mocha/expectation_list.rb

@@ -17,14 +17,18 @@ module Mocha
       @expectations.any? { |expectation| expectation.matches_method?(method_name) }
     end
 
-    def match(invocation)
-      matching_expectations(invocation).first
+    def match(invocation, ignoring_order: false)
+      matching_expectations(invocation, ignoring_order: ignoring_order).first
     end
 
     def match_allowing_invocation(invocation)
       matching_expectations(invocation).detect(&:invocations_allowed?)
     end
 
+    def match_never_allowing_invocation(invocation)
+      matching_expectations(invocation).detect(&:invocations_never_allowed?)
+    end
+
     def verified?(assertion_counter = nil)
       @expectations.all? { |expectation| expectation.verified?(assertion_counter) }
     end
@@ -49,10 +53,8 @@ module Mocha
       self.class.new(to_a + other.to_a)
     end
 
-    private
-
-    def matching_expectations(invocation)
-      @expectations.select { |e| e.match?(invocation) }
+    def matching_expectations(invocation, ignoring_order: false)
+      @expectations.select { |e| e.match?(invocation, ignoring_order: ignoring_order) }
     end
   end
 end

data/lib/mocha/hooks.rb

@@ -7,12 +7,12 @@ module Mocha
   #
   # This module is provided as part of the +Mocha::API+ module and is therefore part of the public API, but should only be used by authors of test libraries and not by typical "users" of Mocha.
   #
-  # Integration with Test::Unit and MiniTest are provided as part of Mocha, because they are (or were once) part of the Ruby standard library. Integration with other test libraries is not provided as *part* of Mocha, but is supported by means of the methods in this module.
+  # Integration with Test::Unit and Minitest are provided as part of Mocha, because they are (or were once) part of the Ruby standard library. Integration with other test libraries is not provided as *part* of Mocha, but is supported by means of the methods in this module.
   #
   # See the code in the +Adapter+ modules for examples of how to use the methods in this module. +Mocha::ExpectationErrorFactory+ may be used if you want +Mocha+ to raise a different type of exception.
   #
   # @see Mocha::Integration::TestUnit::Adapter
-  # @see Mocha::Integration::MiniTest::Adapter
+  # @see Mocha::Integration::Minitest::Adapter
   # @see Mocha::ExpectationErrorFactory
   # @see Mocha::API
   module Hooks
@@ -35,8 +35,14 @@ module Mocha
     # Resets Mocha after a test (only for use by authors of test libraries).
     #
     # This method should be called after each individual test has finished (including after any "teardown" code).
-    def mocha_teardown
-      Mockery.teardown
+    def mocha_teardown(origin = mocha_test_name)
+      Mockery.teardown(origin)
+    end
+
+    # Returns a string representing the unit test name, to be included in some Mocha
+    # to help track down potential bugs.
+    def mocha_test_name
+      nil
     end
   end
 end

data/lib/mocha/inspect.rb

@@ -19,8 +19,19 @@ module Mocha
 
     module HashMethods
       def mocha_inspect
-        unwrapped = collect { |key, value| "#{key.mocha_inspect} => #{value.mocha_inspect}" }.join(', ')
-        Hash.ruby2_keywords_hash?(self) ? unwrapped : "{#{unwrapped}}"
+        if Hash.ruby2_keywords_hash?(self)
+          collect do |key, value|
+            case key
+            when Symbol
+              "#{key}: #{value.mocha_inspect}"
+            else
+              "#{key.mocha_inspect} => #{value.mocha_inspect}"
+            end
+          end.join(', ')
+        else
+          unwrapped = collect { |key, value| "#{key.mocha_inspect} => #{value.mocha_inspect}" }.join(', ')
+          "{#{unwrapped}}"
+        end
       end
     end
 

data/lib/mocha/integration/{mini_test → minitest}/adapter.rb

@@ -4,21 +4,21 @@ require 'mocha/expectation_error_factory'
 
 module Mocha
   module Integration
-    module MiniTest
-      # Integrates Mocha into recent versions of MiniTest.
+    module Minitest
+      # Integrates Mocha into recent versions of Minitest.
       #
       # See the source code for an example of how to integrate Mocha into a test library.
       module Adapter
         include Mocha::API
 
         # @private
-        def self.applicable_to?(mini_test_version)
-          Gem::Requirement.new('>= 3.3.0').satisfied_by?(mini_test_version)
+        def self.applicable_to?(minitest_version)
+          Gem::Requirement.new('>= 3.3.0').satisfied_by?(minitest_version)
         end
 
         # @private
         def self.description
-          'adapter for MiniTest gem >= v3.3.0'
+          'adapter for Minitest gem >= v3.3.0'
         end
 
         # @private
@@ -46,6 +46,21 @@ module Mocha
           super
           mocha_teardown
         end
+
+        # @private
+        def mocha_test_name
+          if respond_to?(:name)
+            test_name = name
+          elsif respond_to?(:__name__) # Older minitest
+            test_name = __name__
+          end
+
+          if test_name
+            "#{self.class.name}##{test_name}"
+          else
+            self.class.name
+          end
+        end
       end
     end
   end

data/lib/mocha/integration/{mini_test → minitest}/exception_translation.rb

@@ -2,10 +2,10 @@ require 'mocha/expectation_error'
 
 module Mocha
   module Integration
-    module MiniTest
+    module Minitest
       def self.translate(exception)
         return exception unless exception.is_a?(::Mocha::ExpectationError)
-        translated_exception = ::MiniTest::Assertion.new(exception.message)
+        translated_exception = ::Minitest::Assertion.new(exception.message)
         translated_exception.set_backtrace(exception.backtrace)
         translated_exception
       end

data/lib/mocha/integration/minitest.rb

@@ -0,0 +1,28 @@
+require 'mocha/debug'
+require 'mocha/detection/minitest'
+require 'mocha/integration/minitest/adapter'
+
+module Mocha
+  module Integration
+    module Minitest
+      def self.activate
+        target = Detection::Minitest.testcase
+        return false unless target
+
+        minitest_version = Gem::Version.new(Detection::Minitest.version)
+        Debug.puts "Detected Minitest version: #{minitest_version}"
+
+        unless Minitest::Adapter.applicable_to?(minitest_version)
+          raise 'Versions of minitest earlier than v3.3.0 are not supported.'
+        end
+
+        unless target < Minitest::Adapter
+          Debug.puts "Applying #{Minitest::Adapter.description}"
+          target.send(:include, Minitest::Adapter)
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/mocha/integration/test_unit/adapter.rb

@@ -37,6 +37,11 @@ module Mocha
 
         private
 
+        # @private
+        def mocha_test_name
+          name
+        end
+
         # @private
         def handle_mocha_expectation_error(exception)
           return false unless exception.is_a?(Mocha::ExpectationError)

data/lib/mocha/minitest.rb

@@ -1,6 +1,6 @@
 require 'mocha/ruby_version'
-require 'mocha/integration/mini_test'
+require 'mocha/integration/minitest'
 
-unless Mocha::Integration::MiniTest.activate
-  raise "MiniTest must be loaded *before* `require 'mocha/minitest'`."
+unless Mocha::Integration::Minitest.activate
+  raise "Minitest must be loaded *before* `require 'mocha/minitest'`."
 end

data/lib/mocha/mock.rb

@@ -8,6 +8,7 @@ require 'mocha/method_matcher'
 require 'mocha/parameters_matcher'
 require 'mocha/argument_iterator'
 require 'mocha/expectation_error_factory'
+require 'mocha/deprecation'
 
 module Mocha
   # Traditional mock object.
@@ -34,6 +35,9 @@ module Mocha
   # while an +expects(:foo).at_least_once+ expectation will always be matched
   # against invocations.
   #
+  # However, note that if the expectation that matches the invocation has a
+  # cardinality of "never", then an unexpected invocation error is reported.
+  #
   # This scheme allows you to:
   #
   # - Set up default stubs in your the +setup+ method of your test class and
@@ -100,7 +104,7 @@ module Mocha
     #
     # @example Setup multiple expectations using +expected_methods_vs_return_values+.
     #   object = mock()
-    #   object.expects(:expected_method_one => :result_one, :expected_method_two => :result_two)
+    #   object.expects(expected_method_one: :result_one, expected_method_two: :result_two)
     #
     #   # is exactly equivalent to
     #
@@ -114,6 +118,7 @@ module Mocha
         method_name = args.shift
         ensure_method_not_already_defined(method_name)
         expectation = Expectation.new(self, method_name, backtrace)
+        expectation.in_sequence(@mockery.sequences.last) if @mockery.sequences.any?
         expectation.returns(args.shift) unless args.empty?
         @expectations.add(expectation)
       end
@@ -138,7 +143,7 @@ module Mocha
     #
     # @example Setup multiple expectations using +stubbed_methods_vs_return_values+.
     #   object = mock()
-    #   object.stubs(:stubbed_method_one => :result_one, :stubbed_method_two => :result_two)
+    #   object.stubs(stubbed_method_one: :result_one, stubbed_method_two: :result_two)
     #
     #   # is exactly equivalent to
     #
@@ -153,6 +158,7 @@ module Mocha
         ensure_method_not_already_defined(method_name)
         expectation = Expectation.new(self, method_name, backtrace)
         expectation.at_least(0)
+        expectation.in_sequence(@mockery.sequences.last) if @mockery.sequences.any?
         expectation.returns(args.shift) unless args.empty?
         @expectations.add(expectation)
       end
@@ -309,22 +315,33 @@ module Mocha
     end
 
     # @private
-    # rubocop:disable Style/MethodMissingSuper
-    def method_missing(symbol, *arguments, &block)
+    def method_missing(symbol, *arguments, &block) # rubocop:disable Style/MethodMissingSuper
       handle_method_call(symbol, arguments, block)
     end
     ruby2_keywords(:method_missing)
-    # rubocop:enable Style/MethodMissingSuper
 
     # @private
-    def handle_method_call(symbol, arguments, block)
+    def handle_method_call(symbol, arguments, block) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       check_expiry
       check_responder_responds_to(symbol)
       invocation = Invocation.new(self, symbol, arguments, block)
-      if (matching_expectation_allowing_invocation = all_expectations.match_allowing_invocation(invocation))
-        matching_expectation_allowing_invocation.invoke(invocation)
-      elsif (matching_expectation = all_expectations.match(invocation)) || (!matching_expectation && !@everything_stubbed)
-        raise_unexpected_invocation_error(invocation, matching_expectation)
+
+      matching_expectations = all_expectations.matching_expectations(invocation)
+
+      index = 0
+      while index < matching_expectations.length
+        matching_expectation = matching_expectations[index]
+        if matching_expectation.invocations_never_allowed?
+          raise_unexpected_invocation_error(invocation, matching_expectation)
+        elsif matching_expectation.invocations_allowed?
+          return matching_expectation.invoke(invocation)
+        end
+        index += 1
+      end
+
+      matching_expectation_ignoring_order = all_expectations.match(invocation, ignoring_order: true)
+      if matching_expectation_ignoring_order || (!matching_expectation_ignoring_order && !@everything_stubbed) # rubocop:disable Style/GuardClause
+        raise_unexpected_invocation_error(invocation, matching_expectation_ignoring_order)
       end
     end
 
@@ -343,8 +360,8 @@ module Mocha
     end
 
     # @private
-    def __expire__
-      @expired = true
+    def __expire__(origin)
+      @expired = origin || true
     end
 
     # @private
@@ -373,7 +390,11 @@ module Mocha
       if @unexpected_invocation.nil?
         @unexpected_invocation = invocation
         matching_expectation.invoke(invocation) if matching_expectation
-        message = "#{@unexpected_invocation.call_description}\n#{@mockery.mocha_inspect}"
+        call_description = @unexpected_invocation.call_description
+        if matching_expectation && !matching_expectation.in_correct_order?
+          call_description += ' invoked out of order'
+        end
+        message = "#{call_description}\n#{@mockery.mocha_inspect}"
       else
         message = @unexpected_invocation.short_call_description
       end
@@ -389,8 +410,10 @@ module Mocha
     def check_expiry
       return unless @expired
 
+      origin = @expired == true ? 'one test' : @expired
+
       sentences = [
-        "#{mocha_inspect} was instantiated in one test but it is receiving invocations within another test.",
+        "#{mocha_inspect} was instantiated in #{origin} but it is receiving invocations within another test.",
         'This can lead to unintended interactions between tests and hence unexpected test failures.',
         'Ensure that every test correctly cleans up any state that it introduces.'
       ]

data/lib/mocha/mockery.rb

@@ -48,8 +48,8 @@ module Mocha
         instance.verify(*args)
       end
 
-      def teardown
-        instance.teardown
+      def teardown(origin = nil)
+        instance.teardown(origin)
       ensure
         @instances.pop
       end
@@ -91,9 +91,9 @@ module Mocha
       end
     end
 
-    def teardown
+    def teardown(origin = nil)
       stubba.unstub_all
-      mocks.each(&:__expire__)
+      mocks.each { |m| m.__expire__(origin) }
       reset
     end
 
@@ -109,12 +109,16 @@ module Mocha
       @state_machines ||= []
     end
 
+    def sequences
+      @sequences ||= []
+    end
+
     def mocha_inspect
-      message = ''
-      message << "unsatisfied expectations:\n- #{unsatisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if unsatisfied_expectations.any?
-      message << "satisfied expectations:\n- #{satisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if satisfied_expectations.any?
-      message << "states:\n- #{state_machines.map(&:mocha_inspect).join("\n- ")}\n" if state_machines.any?
-      message
+      lines = []
+      lines << "unsatisfied expectations:\n- #{unsatisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if unsatisfied_expectations.any?
+      lines << "satisfied expectations:\n- #{satisfied_expectations.map(&:mocha_inspect).join("\n- ")}\n" if satisfied_expectations.any?
+      lines << "states:\n- #{state_machines.map(&:mocha_inspect).join("\n- ")}\n" if state_machines.any?
+      lines.join
     end
 
     def on_stubbing(object, method)

data/lib/mocha/object_methods.rb

@@ -59,7 +59,7 @@ module Mocha
     #
     # @example Setting up multiple expectations on a non-mock object.
     #   product = Product.new
-    #   product.expects(:valid? => true, :save => true)
+    #   product.expects(valid?: true, save: true)
     #
     #   # exactly equivalent to
     #
@@ -108,7 +108,7 @@ module Mocha
     #
     # @example Setting up multiple stubbed methods on a non-mock object.
     #   product = Product.new
-    #   product.stubs(:valid? => true, :save => true)
+    #   product.stubs(valid?: true, save: true)
     #
     #   # exactly equivalent to
     #

data/lib/mocha/parameter_matchers/base.rb

@@ -2,11 +2,6 @@ module Mocha
   module ParameterMatchers
     # @abstract Subclass and implement +#matches?+ and +#mocha_inspect+ to define a custom matcher. Also add a suitably named instance method to {ParameterMatchers} to build an instance of the new matcher c.f. {#equals}.
     class Base
-      # @private
-      def to_matcher(_expectation = nil)
-        self
-      end
-
       # A shorthand way of combining two matchers when both must match.
       #
       # Returns a new {AllOf} parameter matcher combining two matchers using a logical AND.
@@ -21,12 +16,12 @@ module Mocha
       # @example Alternative ways to combine matchers with a logical AND.
       #   object = mock()
       #   object.expects(:run).with(all_of(has_key(:foo), has_key(:bar)))
-      #   object.run(:foo => 'foovalue', :bar => 'barvalue')
+      #   object.run(foo: 'foovalue', bar: 'barvalue')
       #
       #   # is exactly equivalent to
       #
       #   object.expects(:run).with(has_key(:foo) & has_key(:bar))
-      #   object.run(:foo => 'foovalue', :bar => 'barvalue)
+      #   object.run(foo: 'foovalue', bar: 'barvalue)
       def &(other)
         AllOf.new(self, other)
       end
@@ -45,12 +40,12 @@ module Mocha
       # @example Alternative ways to combine matchers with a logical OR.
       #   object = mock()
       #   object.expects(:run).with(any_of(has_key(:foo), has_key(:bar)))
-      #   object.run(:foo => 'foovalue')
+      #   object.run(foo: 'foovalue')
       #
       #   # is exactly equivalent to
       #
       #   object.expects(:run).with(has_key(:foo) | has_key(:bar))
-      #   object.run(:foo => 'foovalue')
+      #   object.run(foo: 'foovalue')
       #
       # @example Using an explicit {Equals} matcher in combination with {#|}.
       #   object.expects(:run).with(equals(1) | equals(2))

data/lib/mocha/parameter_matchers/has_entries.rb

@@ -30,20 +30,25 @@ module Mocha
     # Parameter matcher which matches when actual parameter contains all expected +Hash+ entries.
     class HasEntries < Base
       # @private
-      def initialize(entries)
+      def initialize(entries, exact: false)
         @entries = entries
+        @exact = exact
       end
 
       # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
+        return false unless parameter
+        return false unless parameter.respond_to?(:keys)
+        return false if @exact && @entries.length != parameter.keys.length
+
         has_entry_matchers = @entries.map { |key, value| HasEntry.new(key, value) }
         AllOf.new(*has_entry_matchers).matches?([parameter])
       end
 
       # @private
       def mocha_inspect
-        "has_entries(#{@entries.mocha_inspect})"
+        @exact ? @entries.mocha_inspect : "has_entries(#{@entries.mocha_inspect})"
       end
     end
   end

data/lib/mocha/parameter_matchers/includes.rb

@@ -24,7 +24,7 @@ module Mocha
     # @example Actual parameter includes item which matches nested matcher.
     #   object = mock()
     #   object.expects(:method_1).with(includes(has_key(:key)))
-    #   object.method_1(['foo', 'bar', {:key => 'baz'}])
+    #   object.method_1(['foo', 'bar', {key: 'baz'}])
     #   # no error raised
     #
     # @example Actual parameter does not include item matching nested matcher.
@@ -44,11 +44,11 @@ module Mocha
     # @example Actual parameter is a Hash including the given key.
     #   object = mock()
     #   object.expects(:method_1).with(includes(:bar))
-    #   object.method_1({:foo => 1, :bar => 2})
+    #   object.method_1({foo: 1, bar: 2})
     #   # no error raised
     #
     # @example Actual parameter is a Hash without the given key.
-    #   object.method_1({:foo => 1, :baz => 2})
+    #   object.method_1({foo: 1, baz: 2})
     #   # error raised, because hash does not include key 'bar'
     #
     # @example Actual parameter is a Hash with a key matching the given matcher.

data/lib/mocha/parameter_matchers/instance_methods.rb

@@ -1,3 +1,4 @@
+require 'mocha/parameter_matchers/base'
 require 'mocha/parameter_matchers/equals'
 require 'mocha/parameter_matchers/positional_or_keyword_hash'
 
@@ -6,8 +7,14 @@ module Mocha
     # @private
     module InstanceMethods
       # @private
-      def to_matcher(_expectation = nil)
-        Mocha::ParameterMatchers::Equals.new(self)
+      def to_matcher(expectation: nil, top_level: false)
+        if Base === self
+          self
+        elsif Hash === self && top_level
+          Mocha::ParameterMatchers::PositionalOrKeywordHash.new(self, expectation)
+        else
+          Mocha::ParameterMatchers::Equals.new(self)
+        end
       end
     end
   end
@@ -17,11 +24,3 @@ end
 class Object
   include Mocha::ParameterMatchers::InstanceMethods
 end
-
-# @private
-class Hash
-  # @private
-  def to_matcher(expectation = nil)
-    Mocha::ParameterMatchers::PositionalOrKeywordHash.new(self, expectation)
-  end
-end

data/lib/mocha/parameter_matchers/positional_or_keyword_hash.rb

@@ -1,6 +1,7 @@
 require 'mocha/configuration'
 require 'mocha/deprecation'
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/has_entries'
 
 module Mocha
   module ParameterMatchers
@@ -13,7 +14,8 @@ module Mocha
 
       def matches?(available_parameters)
         parameter, is_last_parameter = extract_parameter(available_parameters)
-        return false unless parameter == @value
+
+        return false unless HasEntries.new(@value, exact: true).matches?([parameter])
 
         if is_last_parameter && !same_type_of_hash?(parameter, @value)
           return false if Mocha.configuration.strict_keyword_argument_matching?