mocha 2.6.1 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 427e4fdcdcceac0496dd9ad52802ae29be41ba102de0888e58f6c379c77ac24e
-  data.tar.gz: d2c3e87c6d5f861f1ae2124b758fd548e19f2299e1ebe69551b7483d0941516d
+  metadata.gz: 61f3a7bc2e73c16b715a31472883ed85fc55726d28e43d051b5d62da21362b52
+  data.tar.gz: 8e2b6b411543932dfb02f9d97cbe0eb35ed48e983e9079a426c7963f075416da
 SHA512:
-  metadata.gz: 7b82f53427cf92b742d97c551808e42f8b954148f7311f97bb52e4c1c15952515cce115e23022ce10a5d52e07238dc8ce7188d810de5f4a7e193ca59d72b2e4f
-  data.tar.gz: c345496f74391ca1b8b2f6a4b0d3947f30c119a89416c7f69037b064c6ca207a77607fa8bd93443152c196f4f5fef93cccc984c4a75040ee675d140237dd0f8b
+  metadata.gz: dd352ea7b0ef64b7e56880a90faecd452b67891765a23441013f73405546da1746314025bb4c556b1322ea621a7d28d940efc77272a52b63716993bc27ebe94f
+  data.tar.gz: e229f55ddd4d53350941bef0af9d3b1026a76f904b666d187ebd6d808feb284101677c66e47005ea3889767626e1cd556330e222d80752f57be89665d4fafd3a

data/Gemfile

@@ -25,6 +25,10 @@ if RUBY_VERSION >= '2.2.0'
   gem 'jaro_winkler', '>= 1.5.5'
   gem 'rubocop', '> 0.56', '<= 0.58.2'
 end
+if RUBY_ENGINE == 'jruby'
+  # Workaround for https://github.com/jruby/jruby/issues/8488
+  gem 'jar-dependencies', '~> 0.4.1'
+end
 if ENV['MOCHA_GENERATE_DOCS']
   gem 'redcarpet'
   gem 'yard'

data/README.md

@@ -8,6 +8,7 @@
 * Supported by many other test frameworks.
 
 ### Intended Usage
+
 Mocha is intended to be used in unit tests for the [Mock Object](http://xunitpatterns.com/Mock%20Object.html) or [Test Stub](http://xunitpatterns.com/Test%20Stub.html) types of [Test Double](http://xunitpatterns.com/Test%20Double.html), not the [Fake Object](http://xunitpatterns.com/Fake%20Object.html) or [Test Spy](http://xunitpatterns.com/Test%20Spy.html) types. Although it would be possible to extend Mocha to allow the implementation of fakes and spies, we have chosen to keep it focused on mocks and stubs.
 
 ### Installation
@@ -276,7 +277,7 @@ Maybe, but probably not. Partial mocking changes the state of objects in the `Ob
 
 Stubs and expectations are basically the same thing. A stub is just an expectation of zero or more invocations. The `Expectation#stubs` method is syntactic sugar to make the intent of the test more explicit.
 
-When a method is invoked on a mock object, the mock object searches through its expectations from newest to oldest to find one that matches the invocation. After the invocation, the matching expectation might stop matching further invocations.
+When a method is invoked on a mock object, the mock object searches through its expectations from newest to oldest to find one that matches the invocation. After the invocation, the matching expectation might stop matching further invocations. If the expectation that matches the invocation has a cardinality of "never", then an unexpected invocation error is reported.
 
 See the [documentation](https://mocha.jamesmead.org/Mocha/Mock.html) for `Mocha::Mock` for further details.
 

data/RELEASE.md

@@ -1,5 +1,34 @@
 # Release Notes
 
+## 2.7.1
+
+### External changes
+
+* Deprecate `Configuration#stubbing_method_on_nil=` (#694)
+* Indicate when parameter matcher logic is defined by block passed to `Expectation#with` (#698, b30e4434)
+* Improve documentation for `Expectation#with`, especially when it is passed a block (#698, #682, #606 & #681)
+
+## 2.7.0
+
+### External changes
+
+* Fail fast if invocation matches never expectation (#679, #678, #490, #131 & #44) - thanks to @ducmtran & @davidstosik for reporting
+
+### Internal changes
+
+* Workaround for JRuby jar-dependencies issue (#690)
+* Ruby v3.4 stacktrace uses single-quote vs backtick (#688 & #689) - thanks to Vít Ondruch
+
+**WARNING: This release fixes a very _old_ bug**
+* The bug relates to the use of `Expectation#never` in combination with other expectations on the same method.
+* Please ensure you fix the relevant deprecation warnings when running against v2.6.1 *before* upgrading to v2.7.0.
+* Previously, the following test would have passed, but now it will fail with an unexpected invocation error on the `foo.bar` line.
+
+    foo = mock('foo')
+    foo.stubs(:bar)
+    foo.expects(:bar).never
+    foo.bar
+
 ## 2.6.1
 
 ### External changes

data/lib/mocha/configuration.rb

@@ -1,4 +1,5 @@
 require 'mocha/ruby_version'
+require 'mocha/deprecation'
 
 module Mocha
   # Allows setting of configuration options. See {Configuration} for the available options.
@@ -206,8 +207,14 @@ module Mocha
     # When +value+ is +:prevent+, raise a {StubbingError}. This is the default.
     #
     # @param [Symbol] value one of +:allow+, +:warn+, +:prevent+.
+    # @deprecated This method is deprecated and will be removed in a future release. +nil+ is frozen in Ruby >= v2.2 and Mocha will be dropping support for Ruby v2.1. At that point it won't be possible to stub methods on +nil+ any more.
     #
     def stubbing_method_on_nil=(value)
+      Deprecation.warning([
+        '`Mocha::Configuration#stubbing_method_on_nil=` is deprecated and will be removed in a future release.',
+        '`nil` is frozen in Ruby >= v2.2 and Mocha will be dropping support for Ruby v2.1.',
+        "At that point it won't be possible to stub methods on `nil` any more."
+      ].join(' '))
       @options[:stubbing_method_on_nil] = value
     end
 

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

data/lib/mocha/mock.rb

@@ -35,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
@@ -326,15 +329,11 @@ module Mocha
       matching_expectations = all_expectations.matching_expectations(invocation)
 
       index = 0
-      never_allowed_expectation = nil
       while index < matching_expectations.length
         matching_expectation = matching_expectations[index]
         if matching_expectation.invocations_never_allowed?
-          never_allowed_expectation = matching_expectation
+          raise_unexpected_invocation_error(invocation, matching_expectation)
         elsif matching_expectation.invocations_allowed?
-          if never_allowed_expectation
-            invocation_not_allowed_warning(invocation, never_allowed_expectation)
-          end
           return matching_expectation.invoke(invocation)
         end
         index += 1
@@ -387,14 +386,6 @@ module Mocha
 
     private
 
-    def invocation_not_allowed_warning(invocation, expectation)
-      messages = [
-        "The expectation defined at #{expectation.definition_location} does not allow invocations, but #{invocation.call_description} was invoked.",
-        'This invocation will cause the test to fail fast in a future version of Mocha.'
-      ]
-      Deprecation.warning(messages.join(' '))
-    end
-
     def raise_unexpected_invocation_error(invocation, matching_expectation)
       if @unexpected_invocation.nil?
         @unexpected_invocation = invocation

data/lib/mocha/parameters_matcher.rb

@@ -22,9 +22,13 @@ module Mocha
     end
 
     def mocha_inspect
-      signature = matchers.mocha_inspect
-      signature = signature.gsub(/^\[|\]$/, '')
-      "(#{signature})"
+      if @matching_block
+        '(arguments_accepted_by_custom_matching_block)'
+      else
+        signature = matchers.mocha_inspect
+        signature = signature.gsub(/^\[|\]$/, '')
+        "(#{signature})"
+      end
     end
 
     def matchers

data/lib/mocha/version.rb

@@ -1,3 +1,3 @@
 module Mocha
-  VERSION = '2.6.1'.freeze
+  VERSION = '2.7.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mocha
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.1
 platform: ruby
 authors:
 - James Mead
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-28 00:00:00.000000000 Z
+date: 2024-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby2_keywords