mocha 2.7.1 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61f3a7bc2e73c16b715a31472883ed85fc55726d28e43d051b5d62da21362b52
-  data.tar.gz: 8e2b6b411543932dfb02f9d97cbe0eb35ed48e983e9079a426c7963f075416da
+  metadata.gz: f100e1c21f105d22752ae4ffc7740ba8fb351559679d3972ae5eea253725e082
+  data.tar.gz: 31729a24bdde2da814bbf7d995fb77fc4c08dd7c98775bdb85d6d36fead87a35
 SHA512:
-  metadata.gz: dd352ea7b0ef64b7e56880a90faecd452b67891765a23441013f73405546da1746314025bb4c556b1322ea621a7d28d940efc77272a52b63716993bc27ebe94f
-  data.tar.gz: e229f55ddd4d53350941bef0af9d3b1026a76f904b666d187ebd6d808feb284101677c66e47005ea3889767626e1cd556330e222d80752f57be89665d4fafd3a
+  metadata.gz: 57b38d4f7b71f41156ea6dd278416864caed11866f1137a5605491000d3603b8793200d6275962b77ed71aaf09707333b88301451b809e9774e3180d594451cf
+  data.tar.gz: 672e486d410a534ecf3eae8613294dfeb894c3fc8d324ae4414328e56ccd31ab9ebb46f13105b95cb3c1b0f35e5cd89eb6eeb5dee7493fbefe200dc03b251f0d

data/RELEASE.md

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

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

@@ -263,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,7 @@ 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.
@@ -207,7 +207,7 @@ 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; +false+ otherwise.

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

data/lib/mocha/parameter_matchers/equivalent_uri.rb

@@ -1,33 +1,40 @@
 require 'mocha/parameter_matchers/base'
+require 'mocha/parameter_matchers/deprecations'
 require 'uri'
 require 'cgi'
 
 module Mocha
   module ParameterMatchers
-    # Matches a URI without regard to the ordering of parameters in the query string.
-    #
-    # @param [String] uri URI to match.
-    # @return [EquivalentUri] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example Actual URI is equivalent.
-    #   object = mock()
-    #   object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2))
-    #   object.method_1('http://example.com/foo?b=2&a=1')
-    #   # no error raised
-    #
-    # @example Actual URI is not equivalent.
-    #   object = mock()
-    #   object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2))
-    #   object.method_1('http://example.com/foo?a=1&b=3')
-    #   # error raised, because the query parameters were different
-    def equivalent_uri(uri)
-      EquivalentUri.new(uri)
+    module Methods
+      # Matches a URI without regard to the ordering of parameters in the query string.
+      #
+      # @param [String] uri URI to match.
+      # @return [EquivalentUri] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Actual URI is equivalent.
+      #   object = mock()
+      #   object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2))
+      #   object.method_1('http://example.com/foo?b=2&a=1')
+      #   # no error raised
+      #
+      # @example Actual URI is not equivalent.
+      #   object = mock()
+      #   object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2))
+      #   object.method_1('http://example.com/foo?a=1&b=3')
+      #   # error raised, because the query parameters were different
+      def equivalent_uri(uri)
+        EquivalentUri.new(uri)
+      end
     end
 
+    define_deprecated_matcher_method(:equivalent_uri)
+
     # Parameter matcher which matches URIs with equivalent query strings.
-    class EquivalentUri < Base
+    class EquivalentUri
+      include BaseMethods
+
       # @private
       def initialize(uri)
         @uri = URI.parse(uri)
@@ -53,5 +60,7 @@ module Mocha
         URI::Generic::COMPONENT.inject({}) { |h, k| h.merge(k => uri.__send__(k)) }.merge(query: query_hash)
       end
     end
+
+    provide_deprecated_access_to(:EquivalentUri)
   end
 end

data/lib/mocha/parameter_matchers/has_entries.rb

@@ -1,34 +1,41 @@
 require 'mocha/parameter_matchers/base'
 require 'mocha/parameter_matchers/all_of'
 require 'mocha/parameter_matchers/has_entry'
+require 'mocha/parameter_matchers/deprecations'
 
 module Mocha
   module ParameterMatchers
-    # Matches +Hash+ containing all +entries+.
-    #
-    # @param [Hash] entries expected +Hash+ entries.
-    # @return [HasEntries] parameter matcher.
-    #
-    # @see Expectation#with
-    #
-    # @example Actual parameter contains all expected entries.
-    #   object = mock()
-    #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
-    #   object.method_1('key_1' => 1, 'key_2' => 2, 'key_3' => 3)
-    #   # no error raised
-    #
-    # @example Actual parameter does not contain all expected entries.
-    #   object = mock()
-    #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
-    #   object.method_1('key_1' => 1, 'key_2' => 99)
-    #   # error raised, because method_1 was not called with Hash containing entries: 'key_1' => 1, 'key_2' => 2
-    #
-    def has_entries(entries) # rubocop:disable Naming/PredicateName
-      HasEntries.new(entries)
+    module Methods
+      # Matches +Hash+ containing all +entries+.
+      #
+      # @param [Hash] entries expected +Hash+ entries.
+      # @return [HasEntries] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Actual parameter contains all expected entries.
+      #   object = mock()
+      #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
+      #   object.method_1('key_1' => 1, 'key_2' => 2, 'key_3' => 3)
+      #   # no error raised
+      #
+      # @example Actual parameter does not contain all expected entries.
+      #   object = mock()
+      #   object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2))
+      #   object.method_1('key_1' => 1, 'key_2' => 99)
+      #   # error raised, because method_1 was not called with Hash containing entries: 'key_1' => 1, 'key_2' => 2
+      #
+      def has_entries(entries) # rubocop:disable Naming/PredicateName
+        HasEntries.new(entries)
+      end
     end
 
+    define_deprecated_matcher_method(:has_entries)
+
     # Parameter matcher which matches when actual parameter contains all expected +Hash+ entries.
-    class HasEntries < Base
+    class HasEntries
+      include BaseMethods
+
       # @private
       def initialize(entries, exact: false)
         @entries = entries
@@ -51,5 +58,7 @@ module Mocha
         @exact ? @entries.mocha_inspect : "has_entries(#{@entries.mocha_inspect})"
       end
     end
+
+    provide_deprecated_access_to(:HasEntries)
   end
 end