mocha 2.7.0 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36441d2fc56cc4d162b3f1e790c6add3c70eebac844ec6e6b275ef1b6e5f268c
-  data.tar.gz: b63504e88684874b3609b91096bcd90d18f31639b3d32ba95e36f48e8fc67ecf
+  metadata.gz: 61f3a7bc2e73c16b715a31472883ed85fc55726d28e43d051b5d62da21362b52
+  data.tar.gz: 8e2b6b411543932dfb02f9d97cbe0eb35ed48e983e9079a426c7963f075416da
 SHA512:
-  metadata.gz: 43c0128284d592878e833404f53f95a3c64bfeca18c85f7f94313b475566f98dc0993ed2b41a9d5118c1b4aabbb99e8848510d7aa3b4afa55804d67c0dd25658
-  data.tar.gz: d9b9785fbf25b80552a7f25e649a5e3ce08ef628c82a1dd36bccf260867156a4ac2c6cf1726e720c6ed8d836a8a1aa0e2441e29e869e65c244ac0c51f93c9423
+  metadata.gz: dd352ea7b0ef64b7e56880a90faecd452b67891765a23441013f73405546da1746314025bb4c556b1322ea621a7d28d940efc77272a52b63716993bc27ebe94f
+  data.tar.gz: e229f55ddd4d53350941bef0af9d3b1026a76f904b666d187ebd6d808feb284101677c66e47005ea3889767626e1cd556330e222d80752f57be89665d4fafd3a

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

data/RELEASE.md

@@ -1,5 +1,13 @@
 # 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

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/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.7.0'.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.7.0
+  version: 2.7.1
 platform: ruby
 authors:
 - James Mead
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-07 00:00:00.000000000 Z
+date: 2024-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby2_keywords