mocha 1.16.1 → 2.7.1

data/lib/mocha/expectation.rb

@@ -1,3 +1,4 @@
+require 'ruby2_keywords'
 require 'mocha/method_matcher'
 require 'mocha/parameters_matcher'
 require 'mocha/expectation_error'
@@ -11,6 +12,7 @@ require 'mocha/change_state_side_effect'
 require 'mocha/cardinality'
 require 'mocha/configuration'
 require 'mocha/block_matcher'
+require 'mocha/backtrace_filter'
 
 module Mocha
   # Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
@@ -187,17 +189,31 @@ module Mocha
       at_most(1)
     end
 
-    # Modifies expectation so that the expected method must be called with +expected_parameters+.
+    # Modifies expectation so that the expected method must be called with +expected_parameters_or_matchers+.
     #
-    # May be used with parameter matchers in {ParameterMatchers}.
+    # 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.
     #
-    # @param [*Array] expected_parameters parameters expected.
+    # 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.
+    #
+    # When {Configuration#strict_keyword_argument_matching=} is set to +true+, an actual positional +Hash+ will not match an expected set of keyword arguments; and vice versa, an actual set of keyword arguments will not match an expected positional +Hash+, i.e. the parameter matching is stricter.
+    #
+    # @see ParameterMatchers
+    # @see Configuration#strict_keyword_argument_matching=
+    #
+    # @param [Array<Object,ParameterMatchers::Base>] expected_parameters_or_matchers expected parameter values or parameter matchers.
     # @yield optional block specifying custom matching.
-    # @yieldparam [*Array] 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 expected parameters.
+    # @example Expected method must be called with exact parameter values.
     #   object = mock()
     #   object.expects(:expected_method).with(:param1, :param2)
     #   object.expected_method(:param1, :param2)
@@ -208,7 +224,44 @@ module Mocha
     #   object.expected_method(:param3)
     #   # => verify fails
     #
-    # @example Expected method must be called with a value divisible by 4.
+    # @example Expected method must be called with parameters matching parameter matchers.
+    #   object = mock()
+    #   object.expects(:expected_method).with(includes('string2'), anything)
+    #   object.expected_method(['string1', 'string2'], 'any-old-value')
+    #   # => verify succeeds
+    #
+    #   object = mock()
+    #   object.expects(:expected_method).with(includes('string2'), anything)
+    #   object.expected_method(['string1'], 'any-old-value')
+    #   # => verify fails
+    #
+    # @example Loose keyword argument matching (default)
+    #
+    #   class Example
+    #     def foo(a, bar:); end
+    #   end
+    #
+    #   example = Example.new
+    #   example.expects(:foo).with('a', bar: 'b')
+    #   example.foo('a', { bar: 'b' })
+    #   # This passes the test, but would result in an ArgumentError in practice
+    #
+    # @example Strict keyword argument matching
+    #
+    #   Mocha.configure do |c|
+    #     c.strict_keyword_argument_matching = true
+    #   end
+    #
+    #   class Example
+    #     def foo(a, bar:); end
+    #   end
+    #
+    #   example = Example.new
+    #   example.expects(:foo).with('a', bar: 'b')
+    #   example.foo('a', { bar: 'b' })
+    #   # This now fails as expected
+    #
+    # @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)
@@ -218,10 +271,27 @@ module Mocha
     #   object.expects(:expected_method).with() { |value| value % 4 == 0 }
     #   object.expected_method(17)
     #   # => verify fails
-    def with(*expected_parameters, &matching_block)
-      @parameters_matcher = ParametersMatcher.new(expected_parameters, &matching_block)
+    #
+    # @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
     end
+    ruby2_keywords(:with)
 
     # Modifies expectation so that the expected method must be called with a block.
     #
@@ -583,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
@@ -598,6 +674,11 @@ module Mocha
       @cardinality.invocations_allowed?
     end
 
+    # @private
+    def invocations_never_allowed?
+      @cardinality.invocations_never_allowed?
+    end
+
     # @private
     def satisfied?
       @cardinality.satisfied?
@@ -625,7 +706,7 @@ module Mocha
     def inspect
       address = __id__ * 2
       address += 0x100000000 if address < 0
-      "#<Expectation:0x#{format('%x', address)} #{mocha_inspect} >"
+      "#<Expectation:0x#{format('%<address>x', address: address)} #{mocha_inspect} >"
     end
 
     # @private
@@ -644,5 +725,11 @@ module Mocha
       signature << " #{@block_matcher.mocha_inspect}" if @block_matcher.mocha_inspect
       signature
     end
+
+    # @private
+    def definition_location
+      filter = BacktraceFilter.new
+      filter.filtered(backtrace)[0]
+    end
   end
 end

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

@@ -6,7 +6,7 @@ module Mocha
       def mocha_inspect
         address = __id__ * 2
         address += 0x100000000 if address < 0
-        inspect =~ /#</ ? "#<#{self.class}:0x#{Kernel.format('%x', address)}>" : inspect
+        inspect =~ /#</ ? "#<#{self.class}:0x#{Kernel.format('%<address>x', address: address)}>" : inspect
       end
     end
 
@@ -18,9 +18,20 @@ module Mocha
     end
 
     module HashMethods
-      def mocha_inspect(wrapped = true)
-        unwrapped = collect { |key, value| "#{key.mocha_inspect} => #{value.mocha_inspect}" }.join(', ')
-        wrapped ? "{#{unwrapped}}" : unwrapped
+      def mocha_inspect
+        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,26 +4,26 @@ 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
         def self.included(_mod)
-          Mocha::ExpectationErrorFactory.exception_class = ::MiniTest::Assertion
+          Mocha::ExpectationErrorFactory.exception_class = ::Minitest::Assertion
         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

@@ -12,7 +12,7 @@ module Mocha
         include Mocha::API
 
         # @private
-        def self.applicable_to?(test_unit_version, _ruby_version = nil)
+        def self.applicable_to?(test_unit_version)
           Gem::Requirement.new('>= 2.5.1').satisfied_by?(test_unit_version)
         end
 
@@ -23,20 +23,25 @@ module Mocha
 
         # @private
         def self.included(mod)
-          mod.setup :mocha_setup, :before => :prepend
+          mod.setup :mocha_setup, before: :prepend
 
           mod.exception_handler(:handle_mocha_expectation_error)
 
-          mod.cleanup :after => :append do
+          mod.cleanup after: :append do
             assertion_counter = Integration::AssertionCounter.new(self)
             mocha_verify(assertion_counter)
           end
 
-          mod.teardown :mocha_teardown, :after => :append
+          mod.teardown :mocha_teardown, after: :append
         end
 
         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/integration/test_unit.rb

@@ -1,47 +1,26 @@
 require 'mocha/debug'
-
 require 'mocha/detection/test_unit'
-
-require 'mocha/integration/test_unit/nothing'
-require 'mocha/integration/test_unit/ruby_version_186_and_above'
-require 'mocha/integration/test_unit/gem_version_200'
-require 'mocha/integration/test_unit/gem_version_201_to_202'
-require 'mocha/integration/test_unit/gem_version_203_to_220'
-require 'mocha/integration/test_unit/gem_version_230_to_250'
 require 'mocha/integration/test_unit/adapter'
 
-require 'mocha/deprecation'
-
 module Mocha
   module Integration
     module TestUnit
       def self.activate
-        return false unless Detection::TestUnit.testcase
-        test_unit_version = Gem::Version.new(Detection::TestUnit.version)
-        ruby_version = Gem::Version.new(RUBY_VERSION.dup)
+        target = Detection::TestUnit.testcase
+        return false unless target
 
-        Debug.puts "Detected Ruby version: #{ruby_version}"
+        test_unit_version = Gem::Version.new(Detection::TestUnit.version)
         Debug.puts "Detected Test::Unit version: #{test_unit_version}"
 
-        integration_module = [
-          TestUnit::Adapter,
-          TestUnit::GemVersion230To250,
-          TestUnit::GemVersion203To220,
-          TestUnit::GemVersion201To202,
-          TestUnit::GemVersion200,
-          TestUnit::RubyVersion186AndAbove,
-          TestUnit::Nothing
-        ].detect { |m| m.applicable_to?(test_unit_version, ruby_version) }
+        unless TestUnit::Adapter.applicable_to?(test_unit_version)
+          raise 'Versions of test-unit earlier than v2.5.1 are not supported.'
+        end
 
-        unless ::Test::Unit::TestCase < integration_module
-          unless integration_module == TestUnit::Adapter
-            Deprecation.warning(
-              'Versions of test-unit earlier than v2.5.1 will not be supported in future versions of Mocha.'
-            )
-          end
-          Debug.puts "Applying #{integration_module.description}"
-          ::Test::Unit::TestCase.send(:include, integration_module)
+        unless target < TestUnit::Adapter
+          Debug.puts "Applying #{TestUnit::Adapter.description}"
+          target.send(:include, TestUnit::Adapter)
         end
+
         true
       end
     end

data/lib/mocha/invocation.rb

@@ -3,8 +3,6 @@ require 'mocha/raised_exception'
 require 'mocha/return_values'
 require 'mocha/thrown_object'
 require 'mocha/yield_parameters'
-require 'mocha/configuration'
-require 'mocha/deprecation'
 
 module Mocha
   class Invocation
@@ -22,18 +20,8 @@ module Mocha
     def call(yield_parameters = YieldParameters.new, return_values = ReturnValues.new)
       yield_parameters.next_invocation.each do |yield_args|
         @yields << ParametersMatcher.new(yield_args)
-        if @block
-          @block.call(*yield_args)
-        else
-          raise LocalJumpError unless Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
-          yield_args_description = ParametersMatcher.new(yield_args).mocha_inspect
-          Deprecation.warning(
-            "Stubbed method was instructed to yield #{yield_args_description}, but no block was given by invocation: #{call_description}.",
-            ' This will raise a LocalJumpError in the future.',
-            ' Use Expectation#with_block_given to constrain this expectation to match invocations supplying a block.',
-            ' And, if necessary, add another expectation to match invocations not supplying a block.'
-          )
-        end
+        raise LocalJumpError unless @block
+        @block.call(*yield_args)
       end
       return_values.next(self)
     end
@@ -79,7 +67,6 @@ module Mocha
     def argument_description
       signature = arguments.mocha_inspect
       signature = signature.gsub(/^\[|\]$/, '')
-      signature = signature.gsub(/^\{|\}$/, '') if arguments.length == 1
       "(#{signature})"
     end
   end

data/lib/mocha/minitest.rb

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