mocha 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36441d2fc56cc4d162b3f1e790c6add3c70eebac844ec6e6b275ef1b6e5f268c
-  data.tar.gz: b63504e88684874b3609b91096bcd90d18f31639b3d32ba95e36f48e8fc67ecf
+  metadata.gz: f100e1c21f105d22752ae4ffc7740ba8fb351559679d3972ae5eea253725e082
+  data.tar.gz: 31729a24bdde2da814bbf7d995fb77fc4c08dd7c98775bdb85d6d36fead87a35
 SHA512:
-  metadata.gz: 43c0128284d592878e833404f53f95a3c64bfeca18c85f7f94313b475566f98dc0993ed2b41a9d5118c1b4aabbb99e8848510d7aa3b4afa55804d67c0dd25658
-  data.tar.gz: d9b9785fbf25b80552a7f25e649a5e3ce08ef628c82a1dd36bccf260867156a4ac2c6cf1726e720c6ed8d836a8a1aa0e2441e29e869e65c244ac0c51f93c9423
+  metadata.gz: 57b38d4f7b71f41156ea6dd278416864caed11866f1137a5605491000d3603b8793200d6275962b77ed71aaf09707333b88301451b809e9774e3180d594451cf
+  data.tar.gz: 672e486d410a534ecf3eae8613294dfeb894c3fc8d324ae4414328e56ccd31ab9ebb46f13105b95cb3c1b0f35e5cd89eb6eeb5dee7493fbefe200dc03b251f0d

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,28 @@
 # Release Notes
 
+## 2.8.0
+
+Many thanks to @etiennebarrie for his help in testing v3.0.0 release candidates which led to many of these changes.
+
+### External changes
+
+* Extract `ParameterMatchers::BaseMethods` module and deprecate inheriting from `ParameterMatchers::Base` class (0ddfbe4b)
+* Move matcher builder methods into `ParameterMatchers::Methods` module and only include that module into `API` (2de41423)
+* Provide deprecated access to matcher builder methods when including `ParameterMatchers` module (299488e1)
+* Provide deprecated access to matcher classes, e.g. `ParameterMatchers::Equals`, from within tests/specs (dcced1b4)
+
+### Internal changes
+
+* Move `ParameterMatchers#parse_option` -> `HasEntry.parse_option` (9e2a6f66)
+
+## 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/api.rb

@@ -32,7 +32,7 @@ module Mocha
   #   sheep.chew
   #   sheep.foo # => raises NoMethodError exception
   module API
-    include ParameterMatchers
+    include ParameterMatchers::Methods
     include Hooks
 
     # @private

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
 
@@ -256,7 +263,7 @@ module Mocha
     #
     # For more details on keyword arguments in Ruby v3, refer to {https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0 this article}.
     #
-    # Note that +Hash+-related matchers such as {ParameterMatchers#has_value} or {ParameterMatchers#has_key} will still treat a positional +Hash+ and a set of keyword arguments the same, so misleading passing tests are still possible when they are used.
+    # Note that +Hash+-related matchers such as {ParameterMatchers::Methods#has_value} or {ParameterMatchers::Methods#has_key} will still treat a positional +Hash+ and a set of keyword arguments the same, so misleading passing tests are still possible when they are used.
     #
     # This configuration option is +false+ by default to enable gradual adoption, but will be +true+ by default in the future.
     #

data/lib/mocha/expectation.rb

@@ -191,7 +191,12 @@ module Mocha
 
     # Modifies expectation so that the expected method must be called with +expected_parameters_or_matchers+.
     #
-    # 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.
+    # May be used with Ruby literals or variables for exact matching or with parameter matchers for less-specific matching, e.g. {ParameterMatchers::Methods#includes}, {ParameterMatchers::Methods#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.
     #
@@ -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::BaseMethods>] 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/parameter_matchers/all_of.rb

@@ -1,31 +1,38 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches if all +matchers+ match.
-    #
-    # @param [*Array<Base>] matchers parameter matchers.
-    # @return [AllOf] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example All parameter matchers match.
-    #   object = mock()
-    #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
-    #   object.method_1([1, 3])
-    #   # no error raised
-    #
-    # @example One of the parameter matchers does not match.
-    #   object = mock()
-    #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
-    #   object.method_1([1, 2])
-    #   # error raised, because method_1 was not called with object including 1 and 3
-    def all_of(*matchers)
-      AllOf.new(*matchers)
+    module Methods
+      # Matches if all +matchers+ match.
+      #
+      # @param [*Array<BaseMethods>] matchers parameter matchers.
+      # @return [AllOf] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example All parameter matchers match.
+      #   object = mock()
+      #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
+      #   object.method_1([1, 3])
+      #   # no error raised
+      #
+      # @example One of the parameter matchers does not match.
+      #   object = mock()
+      #   object.expects(:method_1).with(all_of(includes(1), includes(3)))
+      #   object.method_1([1, 2])
+      #   # error raised, because method_1 was not called with object including 1 and 3
+      def all_of(*matchers)
+        AllOf.new(*matchers)
+      end
     end
 
+    define_deprecated_matcher_method(:all_of)
+
     # Parameter matcher which combines a number of other matchers using a logical AND.
-    class AllOf < Base
+    class AllOf
+      include BaseMethods
+
       # @private
       def initialize(*matchers)
         @matchers = matchers
@@ -42,5 +49,7 @@ module Mocha
         "all_of(#{@matchers.map(&:mocha_inspect).join(', ')})"
       end
     end
+
+    provide_deprecated_access_to(:AllOf)
   end
 end

data/lib/mocha/parameter_matchers/any_of.rb

@@ -1,37 +1,44 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches if any +matchers+ match.
-    #
-    # @param [*Array<Base>] matchers parameter matchers.
-    # @return [AnyOf] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example One parameter matcher matches.
-    #   object = mock()
-    #   object.expects(:method_1).with(any_of(1, 3))
-    #   object.method_1(1)
-    #   # no error raised
-    #
-    # @example The other parameter matcher matches.
-    #   object = mock()
-    #   object.expects(:method_1).with(any_of(1, 3))
-    #   object.method_1(3)
-    #   # no error raised
-    #
-    # @example Neither parameter matcher matches.
-    #   object = mock()
-    #   object.expects(:method_1).with(any_of(1, 3))
-    #   object.method_1(2)
-    #   # error raised, because method_1 was not called with 1 or 3
-    def any_of(*matchers)
-      AnyOf.new(*matchers)
+    module Methods
+      # Matches if any +matchers+ match.
+      #
+      # @param [*Array<BaseMethods>] matchers parameter matchers.
+      # @return [AnyOf] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example One parameter matcher matches.
+      #   object = mock()
+      #   object.expects(:method_1).with(any_of(1, 3))
+      #   object.method_1(1)
+      #   # no error raised
+      #
+      # @example The other parameter matcher matches.
+      #   object = mock()
+      #   object.expects(:method_1).with(any_of(1, 3))
+      #   object.method_1(3)
+      #   # no error raised
+      #
+      # @example Neither parameter matcher matches.
+      #   object = mock()
+      #   object.expects(:method_1).with(any_of(1, 3))
+      #   object.method_1(2)
+      #   # error raised, because method_1 was not called with 1 or 3
+      def any_of(*matchers)
+        AnyOf.new(*matchers)
+      end
     end
 
+    define_deprecated_matcher_method(:any_of)
+
     # Parameter matcher which combines a number of other matchers using a logical OR.
-    class AnyOf < Base
+    class AnyOf
+      include BaseMethods
+
       # @private
       def initialize(*matchers)
         @matchers = matchers
@@ -48,5 +55,7 @@ module Mocha
         "any_of(#{@matchers.map(&:mocha_inspect).join(', ')})"
       end
     end
+
+    provide_deprecated_access_to(:AnyOf)
   end
 end

data/lib/mocha/parameter_matchers/any_parameters.rb

@@ -1,29 +1,36 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches any parameters. This is used as the default for a newly built expectation.
-    #
-    # @return [AnyParameters] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example Any parameters will match.
-    #   object = mock()
-    #   object.expects(:method_1).with(any_parameters)
-    #   object.method_1(1, 2, 3, 4)
-    #   # no error raised
-    #
-    #   object = mock()
-    #   object.expects(:method_1).with(any_parameters)
-    #   object.method_1(5, 6, 7, 8, 9, 0)
-    #   # no error raised
-    def any_parameters
-      AnyParameters.new
+    module Methods
+      # Matches any parameters. This is used as the default for a newly built expectation.
+      #
+      # @return [AnyParameters] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Any parameters will match.
+      #   object = mock()
+      #   object.expects(:method_1).with(any_parameters)
+      #   object.method_1(1, 2, 3, 4)
+      #   # no error raised
+      #
+      #   object = mock()
+      #   object.expects(:method_1).with(any_parameters)
+      #   object.method_1(5, 6, 7, 8, 9, 0)
+      #   # no error raised
+      def any_parameters
+        AnyParameters.new
+      end
     end
 
+    define_deprecated_matcher_method(:any_parameters)
+
     # Parameter matcher which always matches whatever the parameters.
-    class AnyParameters < Base
+    class AnyParameters
+      include BaseMethods
+
       # @private
       def matches?(available_parameters)
         until available_parameters.empty?
@@ -37,5 +44,7 @@ module Mocha
         'any_parameters'
       end
     end
+
+    provide_deprecated_access_to(:AnyParameters)
   end
 end

data/lib/mocha/parameter_matchers/anything.rb

@@ -1,26 +1,33 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches any object.
-    #
-    # @return [Anything] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example Any object will match.
-    #   object = mock()
-    #   object.expects(:method_1).with(anything)
-    #   object.method_1('foo')
-    #   object.method_1(789)
-    #   object.method_1(:bar)
-    #   # no error raised
-    def anything
-      Anything.new
+    module Methods
+      # Matches any object.
+      #
+      # @return [Anything] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Any object will match.
+      #   object = mock()
+      #   object.expects(:method_1).with(anything)
+      #   object.method_1('foo')
+      #   object.method_1(789)
+      #   object.method_1(:bar)
+      #   # no error raised
+      def anything
+        Anything.new
+      end
     end
 
+    define_deprecated_matcher_method(:anything)
+
     # Parameter matcher which always matches a single parameter.
-    class Anything < Base
+    class Anything
+      include BaseMethods
+
       # @private
       def matches?(available_parameters)
         available_parameters.shift
@@ -32,5 +39,7 @@ module Mocha
         'anything'
       end
     end
+
+    provide_deprecated_access_to(:Anything)
   end
 end

data/lib/mocha/parameter_matchers/base.rb

@@ -1,14 +1,17 @@
+require 'mocha/deprecation'
+require 'mocha/parameter_matchers/deprecations'
+
 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
+    # @abstract Include and implement +#matches?+ and +#mocha_inspect+ to define a custom matcher. Also add a suitably named instance method to {Methods} to build an instance of the new matcher c.f. {Methods#equals}.
+    module BaseMethods
       # A shorthand way of combining two matchers when both must match.
       #
       # Returns a new {AllOf} parameter matcher combining two matchers using a logical AND.
       #
       # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # @param [Base] other parameter matcher.
+      # @param [BaseMethods] other parameter matcher.
       # @return [AllOf] parameter matcher.
       #
       # @see Expectation#with
@@ -32,7 +35,7 @@ module Mocha
       #
       # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # @param [Base] other parameter matcher.
+      # @param [BaseMethods] other parameter matcher.
       # @return [AnyOf] parameter matcher.
       #
       # @see Expectation#with
@@ -56,5 +59,20 @@ module Mocha
         AnyOf.new(self, other)
       end
     end
+
+    # @deprecated Include +BaseMethods+ module instead.
+    class Base
+      include BaseMethods
+
+      # @private
+      def self.inherited(subclass)
+        super
+        Deprecation.warning(
+          "Include #{BaseMethods} module into #{subclass} instead of inheriting from #{self}."
+        )
+      end
+    end
+
+    provide_deprecated_access_to(:Base)
   end
 end

data/lib/mocha/parameter_matchers/deprecations.rb

@@ -0,0 +1,46 @@
+require 'mocha/deprecation'
+require 'set'
+
+module Mocha
+  module ParameterMatchers
+    module Methods
+      # @private
+      def self.included(base)
+        base.define_singleton_method(:const_missing) do |name|
+          if ParameterMatchers.access_deprecated?(name)
+            Mocha::ParameterMatchers.const_get(name).tap do |mod|
+              Deprecation.warning(
+                "Referencing #{name} outside its namespace is deprecated. Use fully-qualified #{mod} instead."
+              )
+            end
+          else
+            super(name)
+          end
+        end
+      end
+    end
+
+    # @private
+    @classes_with_access_deprecated = Set.new
+
+    # @private
+    def self.provide_deprecated_access_to(name)
+      @classes_with_access_deprecated.add(name)
+    end
+
+    # @private
+    def self.access_deprecated?(name)
+      @classes_with_access_deprecated.include?(name)
+    end
+
+    # @private
+    def self.define_deprecated_matcher_method(name)
+      define_method(name) do |*args|
+        Deprecation.warning(
+          "Calling #{ParameterMatchers}##{name} is deprecated. Use #{Methods}##{name} instead."
+        )
+        Methods.instance_method(name).bind(self).call(*args)
+      end
+    end
+  end
+end

data/lib/mocha/parameter_matchers/equals.rb

@@ -1,32 +1,39 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches any +Object+ equalling +value+.
-    #
-    # @param [Object] value expected value.
-    # @return [Equals] parameter matcher.
-    #
-    # @see Expectation#with
-    # @see Object#==
-    #
-    # @example Actual parameter equals expected parameter.
-    #   object = mock()
-    #   object.expects(:method_1).with(equals(2))
-    #   object.method_1(2)
-    #   # no error raised
-    #
-    # @example Actual parameter does not equal expected parameter.
-    #   object = mock()
-    #   object.expects(:method_1).with(equals(2))
-    #   object.method_1(3)
-    #   # error raised, because method_1 was not called with an +Object+ that equals 2
-    def equals(value)
-      Equals.new(value)
+    module Methods
+      # Matches any +Object+ equalling +value+.
+      #
+      # @param [Object] value expected value.
+      # @return [Equals] parameter matcher.
+      #
+      # @see Expectation#with
+      # @see Object#==
+      #
+      # @example Actual parameter equals expected parameter.
+      #   object = mock()
+      #   object.expects(:method_1).with(equals(2))
+      #   object.method_1(2)
+      #   # no error raised
+      #
+      # @example Actual parameter does not equal expected parameter.
+      #   object = mock()
+      #   object.expects(:method_1).with(equals(2))
+      #   object.method_1(3)
+      #   # error raised, because method_1 was not called with an +Object+ that equals 2
+      def equals(value)
+        Equals.new(value)
+      end
     end
 
+    define_deprecated_matcher_method(:equals)
+
     # Parameter matcher which matches when actual parameter equals expected value.
-    class Equals < Base
+    class Equals
+      include BaseMethods
+
       # @private
       def initialize(value)
         @value = value
@@ -43,5 +50,7 @@ module Mocha
         @value.mocha_inspect
       end
     end
+
+    provide_deprecated_access_to(:Equals)
   end
 end