mocha 0.10.5 → 1.13.0

data/lib/mocha/parameter_matchers/includes.rb

@@ -1,41 +1,102 @@
+require 'mocha/parameter_matchers/all_of'
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: includes(item) -> parameter_matcher
+    # Matches any object that responds with +true+ to +include?(item)+
+    # for all items.
+    #
+    # @param [*Array] items expected items.
+    # @return [Includes] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter includes all items.
+    #   object = mock()
+    #   object.expects(:method_1).with(includes('foo', 'bar'))
+    #   object.method_1(['foo', 'bar', 'baz'])
+    #   # no error raised
+    #
+    # @example Actual parameter does not include all items.
+    #   object.method_1(['foo', 'baz'])
+    #   # error raised, because ['foo', 'baz'] does not include 'bar'.
+    #
+    # @example Actual parameter includes item which matches nested matcher.
+    #   object = mock()
+    #   object.expects(:method_1).with(includes(has_key(:key)))
+    #   object.method_1(['foo', 'bar', {:key => 'baz'}])
+    #   # no error raised
+    #
+    # @example Actual parameter does not include item matching nested matcher.
+    #   object.method_1(['foo', 'bar', {:other_key => 'baz'}])
+    #   # error raised, because no element matches `has_key(:key)` matcher
     #
-    # Matches any object that responds true to include?(item)
+    # @example Actual parameter is a String including substring.
     #   object = mock()
-    #   object.expects(:method_1).with(includes('foo'))
-    #   object.method_1(['foo', 'bar'])
+    #   object.expects(:method_1).with(includes('bar'))
+    #   object.method_1('foobarbaz')
     #   # no error raised
     #
-    #   object.method_1(['baz'])
-    #   # error raised, because ['baz'] does not include 'foo'.
-    def includes(item)
-      Includes.new(item)
+    # @example Actual parameter is a String not including substring.
+    #   object.method_1('foobaz')
+    #   # error raised, because 'foobaz' does not include 'bar'
+    #
+    # @example Actual parameter is a Hash including the given key.
+    #   object = mock()
+    #   object.expects(:method_1).with(includes(:bar))
+    #   object.method_1({:foo => 1, :bar => 2})
+    #   # no error raised
+    #
+    # @example Actual parameter is a Hash without the given key.
+    #   object.method_1({:foo => 1, :baz => 2})
+    #   # error raised, because hash does not include key 'bar'
+    #
+    # @example Actual parameter is a Hash with a key matching the given matcher.
+    #   object = mock()
+    #   object.expects(:method_1).with(includes(regexp_matches(/ar/)))
+    #   object.method_1({'foo' => 1, 'bar' => 2})
+    #   # no error raised
+    #
+    # @example Actual parameter is a Hash no key matching the given matcher.
+    #   object.method_1({'foo' => 1, 'baz' => 3})
+    #   # error raised, because hash does not include a key matching /ar/
+    def includes(*items)
+      Includes.new(*items)
     end
 
-    class Includes < Base # :nodoc:
-
-      def initialize(item)
-        @item = item
+    # Parameter matcher which matches when actual parameter includes expected values.
+    class Includes < Base
+      # @private
+      def initialize(*items)
+        @items = items
       end
 
+      # @private
+      # rubocop:disable Metrics/PerceivedComplexity
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:include?)
-        return parameter.include?(@item)
+        if @items.size == 1
+          # rubocop:disable Style/GuardClause
+          if parameter.respond_to?(:any?) && !parameter.is_a?(String)
+            parameter = parameter.keys if parameter.is_a?(Hash)
+            return parameter.any? { |p| @items.first.to_matcher.matches?([p]) }
+          else
+            return parameter.include?(@items.first)
+          end
+          # rubocop:enable Style/GuardClause
+        else
+          includes_matchers = @items.map { |item| Includes.new(item) }
+          AllOf.new(*includes_matchers).matches?([parameter])
+        end
       end
+      # rubocop:enable Metrics/PerceivedComplexity
 
+      # @private
       def mocha_inspect
-        "includes(#{@item.mocha_inspect})"
+        item_descriptions = @items.map(&:mocha_inspect)
+        "includes(#{item_descriptions.join(', ')})"
       end
-
     end
-
   end
-  
 end

data/lib/mocha/parameter_matchers/instance_methods.rb

@@ -0,0 +1,18 @@
+require 'mocha/parameter_matchers/equals'
+
+module Mocha
+  module ParameterMatchers
+    # @private
+    module InstanceMethods
+      # @private
+      def to_matcher
+        Mocha::ParameterMatchers::Equals.new(self)
+      end
+    end
+  end
+end
+
+# @private
+class Object
+  include Mocha::ParameterMatchers::InstanceMethods
+end

data/lib/mocha/parameter_matchers/instance_of.rb

@@ -1,17 +1,22 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: instance_of(klass) -> parameter_matcher
-    #
     # Matches any object that is an instance of +klass+
+    #
+    # @param [Class] klass expected class.
+    # @return [InstanceOf] parameter matcher.
+    #
+    # @see Expectation#with
+    # @see Kernel#instance_of?
+    #
+    # @example Actual parameter is an instance of +String+.
     #   object = mock()
     #   object.expects(:method_1).with(instance_of(String))
     #   object.method_1('string')
     #   # no error raised
     #
+    # @example Actual parameter is not an instance of +String+.
     #   object = mock()
     #   object.expects(:method_1).with(instance_of(String))
     #   object.method_1(99)
@@ -19,24 +24,24 @@ module Mocha
     def instance_of(klass)
       InstanceOf.new(klass)
     end
-    
-    class InstanceOf < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter is an instance of the specified class.
+    class InstanceOf < Base
+      # @private
       def initialize(klass)
         @klass = klass
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         parameter.instance_of?(@klass)
       end
-      
+
+      # @private
       def mocha_inspect
         "instance_of(#{@klass.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/is_a.rb

@@ -1,42 +1,48 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: is_a(klass) -> parameter_matcher
+    # Matches any object that is a +klass+.
+    #
+    # @param [Class] klass expected class.
+    # @return [IsA] parameter matcher.
     #
-    # Matches any object that is a +klass+
+    # @see Expectation#with
+    # @see Kernel#is_a?
+    #
+    # @example Actual parameter is a +Integer+.
     #   object = mock()
     #   object.expects(:method_1).with(is_a(Integer))
     #   object.method_1(99)
     #   # no error raised
     #
+    # @example Actual parameter is not a +Integer+.
     #   object = mock()
     #   object.expects(:method_1).with(is_a(Integer))
     #   object.method_1('string')
     #   # error raised, because method_1 was not called with an Integer
-    def is_a(klass)
+    #
+    def is_a(klass) # rubocop:disable Naming/PredicateName
       IsA.new(klass)
     end
-    
-    class IsA < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter is a specific class.
+    class IsA < Base
+      # @private
       def initialize(klass)
         @klass = klass
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         parameter.is_a?(@klass)
       end
-      
+
+      # @private
       def mocha_inspect
         "is_a(#{@klass.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/kind_of.rb

@@ -1,17 +1,22 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: kind_of(klass) -> parameter_matcher
+    # Matches any +Object+ that is a kind of +klass+.
+    #
+    # @param [Class] klass expected class.
+    # @return [KindOf] parameter matcher.
+    #
+    # @see Expectation#with
+    # @see Kernel#kind_of?
     #
-    # Matches any object that is a kind of +klass+
+    # @example Actual parameter is a kind of +Integer+.
     #   object = mock()
     #   object.expects(:method_1).with(kind_of(Integer))
     #   object.method_1(99)
     #   # no error raised
     #
+    # @example Actual parameter is not a kind of +Integer+.
     #   object = mock()
     #   object.expects(:method_1).with(kind_of(Integer))
     #   object.method_1('string')
@@ -19,24 +24,26 @@ module Mocha
     def kind_of(klass)
       KindOf.new(klass)
     end
-    
-    class KindOf < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter is a kind of specified class.
+    class KindOf < Base
+      # @private
       def initialize(klass)
         @klass = klass
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
+        # rubocop:disable Style/ClassCheck
         parameter.kind_of?(@klass)
+        # rubocop:enable Style/ClassCheck
       end
-      
+
+      # @private
       def mocha_inspect
         "kind_of(#{@klass.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/not.rb

@@ -1,42 +1,47 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: Not(parameter_matcher) -> parameter_matcher
+    # Matches if +matcher+ does *not* match.
+    #
+    # @param [Base] matcher matcher whose logic to invert.
+    # @return [Not] parameter matcher.
     #
-    # Matches if +parameter_matcher+ does not match.
+    # @see Expectation#with
+    #
+    # @example Actual parameter does not include the value +1+.
     #   object = mock()
     #   object.expects(:method_1).with(Not(includes(1)))
     #   object.method_1([0, 2, 3])
     #   # no error raised
     #
+    # @example Actual parameter does include the value +1+.
     #   object = mock()
     #   object.expects(:method_1).with(Not(includes(1)))
     #   object.method_1([0, 1, 2, 3])
     #   # error raised, because method_1 was not called with object not including 1
-    def Not(matcher)
+    #
+    def Not(matcher) # rubocop:disable Naming/MethodName
       Not.new(matcher)
     end
-    
-    class Not < Base # :nodoc:
-      
+
+    # Parameter matcher which inverts the logic of the specified matcher using a logical NOT operation.
+    class Not < Base
+      # @private
       def initialize(matcher)
         @matcher = matcher
       end
-    
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         !@matcher.matches?([parameter])
       end
-      
+
+      # @private
       def mocha_inspect
         "Not(#{@matcher.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/optionally.rb

@@ -1,25 +1,31 @@
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: optionally(*parameter_matchers) -> parameter_matcher
-    #
     # Matches optional parameters if available.
+    #
+    # @param [*Array<Base>] matchers matchers for optional parameters.
+    # @return [Optionally] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Only the two required parameters are supplied and they both match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2)
     #   # no error raised
     #
+    # @example Both required parameters and one of the optional parameters are supplied and they all match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3)
     #   # no error raised
     #
+    # @example Both required parameters and both of the optional parameters are supplied and they all match their expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3, 4)
     #   # no error raised
     #
+    # @example One of the actual optional parameters does not match the expected value.
     #   object = mock()
     #   object.expects(:method_1).with(1, 2, optionally(3, 4))
     #   object.method_1(1, 2, 3, 5)
@@ -27,29 +33,29 @@ module Mocha
     def optionally(*matchers)
       Optionally.new(*matchers)
     end
-    
-    class Optionally < Base # :nodoc:
-      
+
+    # Parameter matcher which allows optional parameters to be specified.
+    class Optionally < Base
+      # @private
       def initialize(*parameters)
-        @matchers = parameters.map { |parameter| parameter.to_matcher }
+        @matchers = parameters.map(&:to_matcher)
       end
-      
+
+      # @private
       def matches?(available_parameters)
         index = 0
-        while (available_parameters.length > 0) && (index < @matchers.length) do
+        while !available_parameters.empty? && (index < @matchers.length)
           matcher = @matchers[index]
           return false unless matcher.matches?(available_parameters)
           index += 1
         end
-        return true
+        true
       end
-      
+
+      # @private
       def mocha_inspect
-        "optionally(#{@matchers.map { |matcher| matcher.mocha_inspect }.join(", ") })"
+        "optionally(#{@matchers.map(&:mocha_inspect).join(', ')})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/regexp_matches.rb

@@ -1,44 +1,48 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: regexp_matches(regular_expression) -> parameter_matcher
+    # Matches any object that matches +regexp+.
+    #
+    # @param [Regexp] regexp regular expression to match.
+    # @return [RegexpMatches] parameter matcher.
+    #
+    # @see Expectation#with
     #
-    # Matches any object that matches +regular_expression+.
+    # @example Actual parameter is matched by specified regular expression.
     #   object = mock()
     #   object.expects(:method_1).with(regexp_matches(/e/))
     #   object.method_1('hello')
     #   # no error raised
     #
+    # @example Actual parameter is not matched by specified regular expression.
     #   object = mock()
     #   object.expects(:method_1).with(regexp_matches(/a/))
     #   object.method_1('hello')
-    #   # error raised, because method_1 was not called with a parameter that matched the 
+    #   # error raised, because method_1 was not called with a parameter that matched the
     #   # regular expression
     def regexp_matches(regexp)
       RegexpMatches.new(regexp)
     end
 
-    class RegexpMatches < Base # :nodoc:
-  
+    # Parameter matcher which matches if specified regular expression matches actual paramter.
+    class RegexpMatches < Base
+      # @private
       def initialize(regexp)
         @regexp = regexp
       end
-  
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:=~)
         parameter =~ @regexp
       end
-  
+
+      # @private
       def mocha_inspect
         "regexp_matches(#{@regexp.mocha_inspect})"
       end
-  
     end
-    
   end
-  
 end

data/lib/mocha/parameter_matchers/responds_with.rb

@@ -2,17 +2,22 @@ require 'mocha/parameter_matchers/base'
 require 'yaml'
 
 module Mocha
-
   module ParameterMatchers
-
-    # :call-seq: responds_with(message, result) -> parameter_matcher
-    #
     # Matches any object that responds to +message+ with +result+. To put it another way, it tests the quack, not the duck.
+    #
+    # @param [Symbol] message method to invoke.
+    # @param [Object] result expected result of sending +message+.
+    # @return [RespondsWith] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter responds with "FOO" when :upcase is invoked.
     #   object = mock()
     #   object.expects(:method_1).with(responds_with(:upcase, "FOO"))
     #   object.method_1("foo")
     #   # no error raised, because "foo".upcase == "FOO"
     #
+    # @example Actual parameter does not respond with "FOO" when :upcase is invoked.
     #   object = mock()
     #   object.expects(:method_1).with(responds_with(:upcase, "BAR"))
     #   object.method_1("foo")
@@ -21,23 +26,24 @@ module Mocha
       RespondsWith.new(message, result)
     end
 
-    class RespondsWith < Base # :nodoc:
-
+    # Parameter matcher which matches if actual parameter returns expected result when specified method is invoked.
+    class RespondsWith < Base
+      # @private
       def initialize(message, result)
-        @message, @result = message, result
+        @message = message
+        @result = result
       end
 
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
-        parameter.__send__(@message) == @result
+        @result.to_matcher.matches?([parameter.__send__(@message)])
       end
 
+      # @private
       def mocha_inspect
         "responds_with(#{@message.mocha_inspect}, #{@result.mocha_inspect})"
       end
-      
     end
-    
   end
-  
 end

data/lib/mocha/parameter_matchers/yaml_equivalent.rb

@@ -2,17 +2,21 @@ require 'mocha/parameter_matchers/base'
 require 'yaml'
 
 module Mocha
-
   module ParameterMatchers
-
-    # :call-seq: yaml_equivalent(object) -> parameter_matcher
-    #
     # Matches any YAML that represents the specified +object+
+    #
+    # @param [Object] object object whose YAML to compare.
+    # @return [YamlEquivalent] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter is YAML equivalent of specified +object+.
     #   object = mock()
     #   object.expects(:method_1).with(yaml_equivalent(1, 2, 3))
     #   object.method_1("--- \n- 1\n- 2\n- 3\n")
     #   # no error raised
     #
+    # @example Actual parameter is not YAML equivalent of specified +object+.
     #   object = mock()
     #   object.expects(:method_1).with(yaml_equivalent(1, 2, 3))
     #   object.method_1("--- \n- 1\n- 2\n")
@@ -21,23 +25,25 @@ module Mocha
       YamlEquivalent.new(object)
     end
 
-    class YamlEquivalent < Base # :nodoc:
-
+    # Parameter matcher which matches if actual parameter is YAML equivalent of specified object.
+    class YamlEquivalent < Base
+      # @private
       def initialize(object)
         @object = object
       end
 
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
+        # rubocop:disable Security/YAMLLoad
         @object == YAML.load(parameter)
+        # rubocop:enable Security/YAMLLoad
       end
 
+      # @private
       def mocha_inspect
         "yaml_equivalent(#{@object.mocha_inspect})"
       end
-      
     end
-    
   end
-  
 end

data/lib/mocha/parameter_matchers.rb

@@ -1,11 +1,9 @@
 module Mocha
-  
-  # Used as parameters for Expectation#with to restrict the parameter values which will match the expectation. Can be nested.
+  # Used as parameters for {Expectation#with} to restrict the parameter values which will match the expectation. Can be nested.
   module ParameterMatchers; end
-  
 end
 
-require 'mocha/parameter_matchers/object'
+require 'mocha/parameter_matchers/instance_methods'
 
 require 'mocha/parameter_matchers/all_of'
 require 'mocha/parameter_matchers/any_of'
@@ -15,6 +13,7 @@ require 'mocha/parameter_matchers/equals'
 require 'mocha/parameter_matchers/has_entry'
 require 'mocha/parameter_matchers/has_entries'
 require 'mocha/parameter_matchers/has_key'
+require 'mocha/parameter_matchers/has_keys'
 require 'mocha/parameter_matchers/has_value'
 require 'mocha/parameter_matchers/includes'
 require 'mocha/parameter_matchers/instance_of'
@@ -25,4 +24,4 @@ require 'mocha/parameter_matchers/optionally'
 require 'mocha/parameter_matchers/regexp_matches'
 require 'mocha/parameter_matchers/responds_with'
 require 'mocha/parameter_matchers/yaml_equivalent'
-require 'mocha/parameter_matchers/query_string'
+require 'mocha/parameter_matchers/equivalent_uri'