mocha 0.10.5 → 1.13.0

data/lib/mocha/parameter_matchers/any_parameters.rb

@@ -1,12 +1,14 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: any_parameters() -> parameter_matcher
+    # Matches any parameters. This is used as the default for a newly built expectation.
+    #
+    # @return [AnyParameters] parameter matcher.
     #
-    # Matches any parameters.
+    # @see Expectation#with
+    #
+    # @example Any parameters will match.
     #   object = mock()
     #   object.expects(:method_1).with(any_parameters)
     #   object.method_1(1, 2, 3, 4)
@@ -20,21 +22,20 @@ module Mocha
       AnyParameters.new
     end
 
-    class AnyParameters < Base # :nodoc:
-      
+    # Parameter matcher which always matches whatever the parameters.
+    class AnyParameters < Base
+      # @private
       def matches?(available_parameters)
-        while available_parameters.length > 0 do
+        until available_parameters.empty?
           available_parameters.shift
         end
-        return true
+        true
       end
 
+      # @private
       def mocha_inspect
-        "any_parameters"
+        'any_parameters'
       end
-
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/anything.rb

@@ -1,33 +1,36 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: anything() -> parameter_matcher
-    #
     # 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
-    
-    class Anything < Base # :nodoc:
-    
+
+    # Parameter matcher which always matches a single parameter.
+    class Anything < Base
+      # @private
       def matches?(available_parameters)
         available_parameters.shift
-        return true
+        true
       end
-      
+
+      # @private
       def mocha_inspect
-        "anything"
+        'anything'
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/base.rb

@@ -1,63 +1,65 @@
 module Mocha
-  
   module ParameterMatchers
-    
-    class Base 
-      
-      def to_matcher # :nodoc:
+    # @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
+      # @private
+      def to_matcher
         self
       end
-      
-      # :call-seq: &(matcher) -> parameter_matcher
+
+      # A shorthand way of combining two matchers when both must match.
       #
-      # A short hand way of specifying multiple matchers that should
-      # all match.
+      # Returns a new {AllOf} parameter matcher combining two matchers using a logical AND.
       #
-      # Returns a new +AllOf+ parameter matcher combining the
-      # given matcher and the receiver.
+      # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # The following statements are equivalent:
+      # @param [Base] other parameter matcher.
+      # @return [AllOf] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @example Alternative ways to combine matchers with a logical AND.
       #   object = mock()
       #   object.expects(:run).with(all_of(has_key(:foo), has_key(:bar)))
       #   object.run(:foo => 'foovalue', :bar => 'barvalue')
       #
-      #   # with the shorthand
+      #   # is exactly equivalent to
+      #
       #   object.expects(:run).with(has_key(:foo) & has_key(:bar))
       #   object.run(:foo => 'foovalue', :bar => 'barvalue)
-      def &(matcher)
-        AllOf.new(self, matcher)
+      def &(other)
+        AllOf.new(self, other)
       end
-      
-      # :call-seq: |(matcher) -> parameter_matcher
+
+      # A shorthand way of combining two matchers when at least one must match.
+      #
+      # Returns a new +AnyOf+ parameter matcher combining two matchers using a logical OR.
       #
-      # A short hand way of specifying multiple matchers, only at least
-      # one of which should pass.
+      # This shorthand will not work with an implicit equals match. Instead, an explicit {Equals} matcher should be used.
       #
-      # Returns a new +AnyOf+ parameter matcher combining the
-      # given matcher and the receiver.
+      # @param [Base] other parameter matcher.
+      # @return [AnyOf] parameter matcher.
       #
-      # The following statements are equivalent:
+      # @see Expectation#with
+      #
+      # @example Alternative ways to combine matchers with a logical OR.
       #   object = mock()
       #   object.expects(:run).with(any_of(has_key(:foo), has_key(:bar)))
       #   object.run(:foo => 'foovalue')
       #
-      #   # with the shorthand
+      #   # is exactly equivalent to
+      #
       #   object.expects(:run).with(has_key(:foo) | has_key(:bar))
       #   object.run(:foo => 'foovalue')
       #
-      # This shorthand will not work with an implicit equals match. Instead,
-      # an explicit equals matcher should be used:
-      #
+      # @example Using an explicit {Equals} matcher in combination with {#|}.
       #   object.expects(:run).with(equals(1) | equals(2))
       #   object.run(1) # passes
       #   object.run(2) # passes
       #   object.run(3) # fails
-      def |(matcher)
-        AnyOf.new(self, matcher)
+      def |(other)
+        AnyOf.new(self, other)
       end
-      
     end
-    
   end
-  
 end

data/lib/mocha/parameter_matchers/equals.rb

@@ -1,42 +1,47 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: equals(value) -> parameter_matcher
+    # Matches any +Object+ equalling +value+.
+    #
+    # @param [Object] value expected value.
+    # @return [Equals] parameter matcher.
+    #
+    # @see Expectation#with
+    # @see Object#==
     #
-    # Matches +Object+ equalling +value+.
+    # @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 Object equalling 3
+    #   # error raised, because method_1 was not called with an +Object+ that equals 2
     def equals(value)
       Equals.new(value)
     end
 
-    class Equals < Base # :nodoc:
-      
+    # Parameter matcher which matches when actual parameter equals expected value.
+    class Equals < Base
+      # @private
       def initialize(value)
         @value = value
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         parameter == @value
       end
-      
+
+      # @private
       def mocha_inspect
         @value.mocha_inspect
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/equivalent_uri.rb

@@ -0,0 +1,58 @@
+require 'mocha/deprecation'
+require 'mocha/parameter_matchers/base'
+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)
+    end
+
+    # Parameter matcher which matches URIs with equivalent query strings.
+    class EquivalentUri < Base
+      # @private
+      def initialize(uri)
+        @uri = URI.parse(uri)
+      end
+
+      # @private
+      def matches?(available_parameters)
+        actual = explode(URI.parse(available_parameters.shift))
+        expected = explode(@uri)
+        actual == expected
+      end
+
+      # @private
+      def mocha_inspect
+        "equivalent_uri(#{@uri.mocha_inspect})"
+      end
+
+      private
+
+      # @private
+      def explode(uri)
+        query_hash = CGI.parse(uri.query || '')
+        URI::Generic::COMPONENT.inject({}) { |h, k| h.merge(k => uri.__send__(k)) }.merge(:query => query_hash)
+      end
+    end
+  end
+end

data/lib/mocha/parameter_matchers/has_entries.rb

@@ -3,43 +3,48 @@ require 'mocha/parameter_matchers/all_of'
 require 'mocha/parameter_matchers/has_entry'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: has_entries(entries) -> parameter_matcher
-    #
     # 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)
+    #
+    def has_entries(entries) # rubocop:disable Naming/PredicateName
       HasEntries.new(entries)
     end
-    
-    class HasEntries < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter contains all expected +Hash+ entries.
+    class HasEntries < Base
+      # @private
       def initialize(entries)
         @entries = entries
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         has_entry_matchers = @entries.map { |key, value| HasEntry.new(key, value) }
         AllOf.new(*has_entry_matchers).matches?([parameter])
       end
-      
+
+      # @private
       def mocha_inspect
         "has_entries(#{@entries.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/has_entry.rb

@@ -1,66 +1,98 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: has_entry(key, value) -> parameter_matcher
-    #            has_entry(key => value) -> parameter_matcher
-    #
     # Matches +Hash+ containing entry with +key+ and +value+.
+    #
+    # @overload def has_entry(key, value)
+    #   @param [Object] key key for entry.
+    #   @param [Object] value value for entry.
+    # @overload def has_entry(single_entry_hash)
+    #   @param [Hash] single_entry_hash +Hash+ with single entry.
+    #   @raise [ArgumentError] if +single_entry_hash+ does not contain exactly one entry.
+    #
+    # @return [HasEntry] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter contains expected entry supplied as key and value.
     #   object = mock()
     #   object.expects(:method_1).with(has_entry('key_1', 1))
     #   object.method_1('key_1' => 1, 'key_2' => 2)
     #   # no error raised
     #
+    # @example Actual parameter contains expected entry supplied as +Hash+ entry.
     #   object = mock()
     #   object.expects(:method_1).with(has_entry('key_1' => 1))
     #   object.method_1('key_1' => 1, 'key_2' => 2)
     #   # no error raised
     #
+    # @example Actual parameter does not contain expected entry supplied as key and value.
     #   object = mock()
     #   object.expects(:method_1).with(has_entry('key_1', 1))
     #   object.method_1('key_1' => 2, 'key_2' => 1)
     #   # error raised, because method_1 was not called with Hash containing entry: 'key_1' => 1
     #
+    # @example Actual parameter does not contain expected entry supplied as +Hash+ entry.
+    #
     #   object = mock()
     #   object.expects(:method_1).with(has_entry('key_1' => 1))
     #   object.method_1('key_1' => 2, 'key_2' => 1)
     #   # error raised, because method_1 was not called with Hash containing entry: 'key_1' => 1
-    def has_entry(*options)
-      key, value = options.shift, options.shift
-      if key.is_a?(Hash)
-        case key.length
-        when 0
-          raise ArgumentError.new("Argument has no entries.")
-        when 1
-          key, value = key.to_a.flatten
-        else
-          raise ArgumentError.new("Argument has multiple entries. Use Mocha::ParameterMatchers#has_entries instead.")
-        end
+    #
+    def has_entry(*options) # rubocop:disable Naming/PredicateName
+      case options.length
+      when 0
+        raise ArgumentError, 'No arguments. Expecting at least one.'
+      when 1
+        key, value = parse_option(options[0])
+      when 2
+        key, value = options
+      else
+        raise ArgumentError, 'Too many arguments; use either a single argument (must be a Hash) or two arguments (a key and a value).'
       end
       HasEntry.new(key, value)
     end
-    
-    class HasEntry < Base # :nodoc:
-      
+
+    # Parameter matcher which matches when actual parameter contains expected +Hash+ entry.
+    class HasEntry < Base
+      # @private
       def initialize(key, value)
-        @key, @value = key, value
+        @key = key
+        @value = value
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:keys) && parameter.respond_to?(:[])
         matching_keys = parameter.keys.select { |key| @key.to_matcher.matches?([key]) }
         matching_keys.any? { |key| @value.to_matcher.matches?([parameter[key]]) }
       end
-      
+
+      # @private
       def mocha_inspect
         "has_entry(#{@key.mocha_inspect} => #{@value.mocha_inspect})"
       end
-      
     end
-    
+
+    private
+
+    # @private
+    def parse_option(option)
+      case option
+      when Hash
+        case option.length
+        when 0
+          raise ArgumentError, 'Argument has no entries.'
+        when 1
+          option.first
+        else
+          raise ArgumentError, 'Argument has multiple entries. Use Mocha::ParameterMatchers#has_entries instead.'
+        end
+      else
+        raise ArgumentError, 'Argument is not a Hash.'
+      end
+    end
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/has_key.rb

@@ -1,43 +1,48 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: has_key(key) -> parameter_matcher
-    #
     # Matches +Hash+ containing +key+.
+    #
+    # @param [Object] key expected key.
+    # @return [HasKey] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter contains entry with expected key.
     #   object = mock()
     #   object.expects(:method_1).with(has_key('key_1'))
     #   object.method_1('key_1' => 1, 'key_2' => 2)
     #   # no error raised
     #
+    # @example Actual parameter does not contain entry with expected key.
     #   object = mock()
     #   object.expects(:method_1).with(has_key('key_1'))
     #   object.method_1('key_2' => 2)
     #   # error raised, because method_1 was not called with Hash containing key: 'key_1'
-    def has_key(key)
+    #
+    def has_key(key) # rubocop:disable Naming/PredicateName
       HasKey.new(key)
     end
 
-    class HasKey < Base # :nodoc:
-      
+    # Parameter matcher which matches when actual parameter contains +Hash+ entry with expected key.
+    class HasKey < Base
+      # @private
       def initialize(key)
         @key = key
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:keys)
         parameter.keys.any? { |key| @key.to_matcher.matches?([key]) }
       end
-      
+
+      # @private
       def mocha_inspect
         "has_key(#{@key.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end

data/lib/mocha/parameter_matchers/has_keys.rb

@@ -0,0 +1,53 @@
+require 'mocha/parameter_matchers/base'
+
+module Mocha
+  module ParameterMatchers
+    # Matches +Hash+ containing +keys+.
+    #
+    # @param [*Array<Object>] keys expected keys.
+    # @return [HasKeys] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter contains entry with expected keys.
+    #   object = mock()
+    #   object.expects(:method_1).with(has_keys(:key_1, :key_2))
+    #   object.method_1(:key_1 => 1, :key_2 => 2, :key_3 => 3)
+    #   # no error raised
+    #
+    # @example Actual parameter does not contain all expected keys.
+    #   object = mock()
+    #   object.expects(:method_1).with(has_keys(:key_1, :key_2))
+    #   object.method_1(:key_2 => 2)
+    #   # error raised, because method_1 was not called with Hash containing key: :key_1
+    #
+    def has_keys(*keys) # rubocop:disable Naming/PredicateName
+      HasKeys.new(*keys)
+    end
+
+    # Parameter matcher which matches when actual parameter contains +Hash+ with all expected keys.
+    class HasKeys < Base
+      # @private
+      def initialize(*keys)
+        raise ArgumentError, 'No arguments. Expecting at least one.' if keys.empty?
+
+        @keys = keys
+      end
+
+      # @private
+      def matches?(available_parameters)
+        parameter = available_parameters.shift
+        return false unless parameter.respond_to?(:keys)
+
+        @keys.map(&:to_matcher).all? do |matcher|
+          parameter.keys.any? { |key| matcher.matches?([key]) }
+        end
+      end
+
+      # @private
+      def mocha_inspect
+        "has_keys(#{@keys.mocha_inspect(false)})"
+      end
+    end
+  end
+end

data/lib/mocha/parameter_matchers/has_value.rb

@@ -1,43 +1,48 @@
 require 'mocha/parameter_matchers/base'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: has_value(value) -> parameter_matcher
-    #
     # Matches +Hash+ containing +value+.
+    #
+    # @param [Object] value expected value.
+    # @return [HasValue] parameter matcher.
+    #
+    # @see Expectation#with
+    #
+    # @example Actual parameter contains entry with expected value.
     #   object = mock()
     #   object.expects(:method_1).with(has_value(1))
     #   object.method_1('key_1' => 1, 'key_2' => 2)
     #   # no error raised
     #
+    # @example Actual parameter does not contain entry with expected value.
     #   object = mock()
     #   object.expects(:method_1).with(has_value(1))
     #   object.method_1('key_2' => 2)
     #   # error raised, because method_1 was not called with Hash containing value: 1
-    def has_value(value)
+    #
+    def has_value(value) # rubocop:disable Naming/PredicateName
       HasValue.new(value)
     end
 
-    class HasValue < Base # :nodoc:
-      
+    # Parameter matcher which matches when actual parameter contains +Hash+ entry with expected value.
+    class HasValue < Base
+      # @private
       def initialize(value)
         @value = value
       end
-      
+
+      # @private
       def matches?(available_parameters)
         parameter = available_parameters.shift
         return false unless parameter.respond_to?(:values)
         parameter.values.any? { |value| @value.to_matcher.matches?([value]) }
       end
-      
+
+      # @private
       def mocha_inspect
         "has_value(#{@value.mocha_inspect})"
       end
-      
     end
-    
   end
-  
-end
+end