mocha 0.5.6 → 3.1.0

data/lib/mocha/parameter_matchers/positional_or_keyword_hash.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'mocha/configuration'
+require 'mocha/deprecation'
+require 'mocha/ruby_version'
+require 'mocha/parameter_matchers/base_methods'
+require 'mocha/parameter_matchers/has_entries'
+
+module Mocha
+  module ParameterMatchers
+    # @private
+    class PositionalOrKeywordHash
+      include BaseMethods
+
+      def initialize(expected_value, expectation, last_expected_value)
+        @expected_value = expected_value
+        @expectation = expectation
+        @last_expected_value = last_expected_value
+      end
+
+      def matches?(actual_values)
+        actual_value, is_last_actual_value = extract_actual_value(actual_values)
+
+        if !matches_entries_exactly?(actual_value)
+          false
+        elsif is_last_actual_value
+          matches_last_actual_value?(actual_value)
+        else
+          true
+        end
+      end
+
+      def mocha_inspect
+        @expected_value.mocha_inspect
+      end
+
+      private
+
+      def matches_entries_exactly?(actual_value)
+        HasEntries.new(@expected_value, exact: true).matches?([actual_value])
+      end
+
+      def matches_last_actual_value?(actual_value)
+        if same_type_of_hash?(actual_value, @expected_value)
+          true
+        elsif last_expected_value_is_positional_hash? # rubocop:disable Lint/DuplicateBranch
+          true
+        elsif Mocha.configuration.strict_keyword_argument_matching?
+          false
+        else
+          deprecation_warning(actual_value, @expected_value) if Mocha::RUBY_V27_PLUS
+          true
+        end
+      end
+
+      def last_expected_value_is_positional_hash?
+        @last_expected_value && !ruby2_keywords_hash?(@expected_value)
+      end
+
+      def extract_actual_value(actual_values)
+        [actual_values.shift, actual_values.empty?]
+      end
+
+      def same_type_of_hash?(actual, expected)
+        ruby2_keywords_hash?(actual) == ruby2_keywords_hash?(expected)
+      end
+
+      def deprecation_warning(actual, expected)
+        details1 = "Expectation #{expectation_definition} expected #{hash_type(expected)} (#{expected.mocha_inspect}),".squeeze(' ')
+        details2 = "but received #{hash_type(actual)} (#{actual.mocha_inspect})."
+        sentence1 = 'These will stop matching when strict keyword argument matching is enabled.'
+        sentence2 = 'See the documentation for Mocha::Configuration#strict_keyword_argument_matching=.'
+        Deprecation.warning([details1, details2, sentence1, sentence2].join(' '))
+      end
+
+      def hash_type(hash)
+        ruby2_keywords_hash?(hash) ? 'keyword arguments' : 'positional hash'
+      end
+
+      def ruby2_keywords_hash?(hash)
+        hash.is_a?(Hash) && ::Hash.ruby2_keywords_hash?(hash)
+      end
+
+      def expectation_definition
+        return nil unless @expectation
+
+        "defined at #{@expectation.definition_location}"
+      end
+    end
+  end
+end

data/lib/mocha/parameter_matchers/regexp_matches.rb

@@ -1,43 +1,55 @@
-require 'mocha/parameter_matchers/base'
+# frozen_string_literal: true
+
+require 'mocha/parameter_matchers/base_methods'
 
 module Mocha
-  
   module ParameterMatchers
-
-    # :call-seq: regexp_matches(regexp) -> parameter_matcher
-    #
-    # Matches any object that matches the regular expression, +regexp+.
-    #   object = mock()
-    #   object.expects(:method_1).with(regexp_matches(/e/))
-    #   object.method_1('hello')
-    #   # no error raised
-    #
-    #   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 
-    #   # regular expression
-    def regexp_matches(regexp)
-      RegexpMatches.new(regexp)
+    module Methods
+      # Matches any object that matches +regexp+.
+      #
+      # @param [Regexp] regexp regular expression to match.
+      # @return [RegexpMatches] parameter matcher.
+      #
+      # @see Expectation#with
+      #
+      # @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
+      #   # regular expression
+      def regexp_matches(regexp)
+        RegexpMatches.new(regexp)
+      end
     end
 
-    class RegexpMatches < Base # :nodoc:
-  
+    # Parameter matcher which matches if specified regular expression matches actual paramter.
+    class RegexpMatches
+      include BaseMethods
+
+      # @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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'mocha/parameter_matchers/base_methods'
+require 'mocha/parameter_matchers/all_of'
+require 'yaml'
+
+module Mocha
+  module ParameterMatchers
+    module Methods
+      # @overload def responds_with(message, result)
+      #   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+.
+      # @overload def responds_with(messages_vs_results)
+      #   Matches any object that responds to all the messages with the corresponding results as specified by +messages_vs_results+.
+      #   @param [Hash<Symbol,Object>] messages_vs_results +Hash+ of messages vs results.
+      #   @raise [ArgumentError] if +messages_vs_results+ does not contain at least one entry.
+      #
+      # @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")
+      #   # error raised, because "foo".upcase != "BAR"
+      #
+      # @example Actual parameter responds with "FOO" when :upcase is invoked and "oof" when :reverse is invoked.
+      #   object = mock()
+      #   object.expects(:method_1).with(responds_with(upcase: "FOO", reverse: "oof"))
+      #   object.method_1("foo")
+      #   # no error raised, because "foo".upcase == "FOO" and "foo".reverse == "oof"
+      def responds_with(*options)
+        case options.length
+        when 0
+          raise ArgumentError, 'No arguments. Expecting at least one.'
+        when 1
+          option = options.first
+          raise ArgumentError, 'Argument is not a Hash.' unless option.is_a?(Hash)
+          raise ArgumentError, 'Argument has no entries.' if option.empty?
+
+          matchers = option.map { |message, result| RespondsWith.new(message, result) }
+          AllOf.new(*matchers)
+        when 2
+          message, result = options
+          RespondsWith.new(message, result)
+        else
+          raise ArgumentError, 'Too many arguments; use either a single argument (must be a Hash) or two arguments (a message and a result).'
+        end
+      end
+    end
+
+    # Parameter matcher which matches if actual parameter returns expected result when specified method is invoked.
+    class RespondsWith
+      include BaseMethods
+
+      # @private
+      def initialize(message, result)
+        @message = message
+        @result = result
+      end
+
+      # @private
+      def matches?(available_parameters)
+        parameter = available_parameters.shift
+        @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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'mocha/parameter_matchers/base_methods'
+require 'yaml'
+
+module Mocha
+  module ParameterMatchers
+    module Methods
+      # 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")
+      #   # error raised, because method_1 was not called with YAML representing the specified Array
+      def yaml_equivalent(object)
+        YamlEquivalent.new(object)
+      end
+    end
+
+    # Parameter matcher which matches if actual parameter is YAML equivalent of specified object.
+    class YamlEquivalent
+      include BaseMethods
+
+      # @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,14 @@
+# frozen_string_literal: true
+
 module Mocha
-  
-  # Used as parameters for Expectation#with to restrict the parameter values which will match the expectation.
-  module ParameterMatchers; end
-  
+  # Matcher classes used as parameters for {Expectation#with} to restrict the parameter values which will match the expectation. Can be nested. Build matcher instances in tests using methods in {Methods}, e.g. {Methods#includes}.
+  module ParameterMatchers
+    # These methods build instances of the {ParameterMatchers} classes which are used with {Expectation#with} to restrict the parameter values. Can be nested, e.g. see {Methods#all_of} examples.
+    module Methods; end
+  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 +18,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'
@@ -23,3 +27,6 @@ require 'mocha/parameter_matchers/kind_of'
 require 'mocha/parameter_matchers/not'
 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/equivalent_uri'

data/lib/mocha/parameters_matcher.rb

@@ -1,37 +1,46 @@
+# frozen_string_literal: true
+
 require 'mocha/inspect'
 require 'mocha/parameter_matchers'
 
 module Mocha
-  
   class ParametersMatcher
-    
-    def initialize(expected_parameters = [ParameterMatchers::AnyParameters.new], &matching_block)
-      @expected_parameters, @matching_block = expected_parameters, matching_block
+    def initialize(expected_parameters = [ParameterMatchers::AnyParameters.new], expectation = nil, &matching_block)
+      @expected_parameters = expected_parameters
+      @expectation = expectation
+      @matching_block = matching_block
     end
-    
+
     def match?(actual_parameters = [])
       if @matching_block
-        return @matching_block.call(*actual_parameters)
+        @matching_block.call(*actual_parameters)
       else
-        return parameters_match?(actual_parameters)
+        parameters_match?(actual_parameters)
       end
     end
-    
+
     def parameters_match?(actual_parameters)
-      matchers.all? { |matcher| matcher.matches?(actual_parameters) } && (actual_parameters.length == 0)
+      matchers.all? { |matcher| matcher.matches?(actual_parameters) } && actual_parameters.empty?
     end
-    
+
     def mocha_inspect
-      signature = matchers.mocha_inspect
-      signature = signature.gsub(/^\[|\]$/, '')
-      signature = signature.gsub(/^\{|\}$/, '') if matchers.length == 1
-      "(#{signature})"
+      if @matching_block
+        '(arguments_accepted_by_custom_matching_block)'
+      else
+        signature = matchers.mocha_inspect
+        signature = signature.gsub(/^\[|\]$/, '')
+        "(#{signature})"
+      end
     end
-    
+
     def matchers
-      @expected_parameters.map { |parameter| parameter.to_matcher }
+      @expected_parameters.map.with_index do |parameter, index|
+        parameter.to_matcher(
+          expectation: @expectation,
+          top_level: true,
+          last: index == @expected_parameters.length - 1
+        )
+      end
     end
-    
   end
-
-end
+end

data/lib/mocha/raised_exception.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mocha
+  class RaisedException
+    def initialize(exception)
+      @exception = exception
+    end
+
+    def mocha_inspect
+      "raised #{@exception}"
+    end
+  end
+end

data/lib/mocha/return_values.rb

@@ -1,34 +1,29 @@
+# frozen_string_literal: true
+
 require 'mocha/single_return_value'
 
-module Mocha # :nodoc:
-  
-  class ReturnValues # :nodoc:
-    
+module Mocha
+  class ReturnValues
     def self.build(*values)
       new(*values.map { |value| SingleReturnValue.new(value) })
     end
-    
+
     attr_accessor :values
-    
+
     def initialize(*values)
       @values = values
     end
-    
-    def next
+
+    def next(invocation)
       case @values.length
-        when 0
-          nil
-        when 1
-          @values.first.evaluate
-        else
-          @values.shift.evaluate
+      when 0 then nil
+      when 1 then @values.first.evaluate(invocation)
+      else @values.shift.evaluate(invocation)
       end
     end
-    
+
     def +(other)
       self.class.new(*(@values + other.values))
     end
-    
   end
-  
-end
+end

data/lib/mocha/ruby_version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mocha
+  RUBY_V27_PLUS = Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.7')
+  RUBY_V30_PLUS = Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('3.0')
+  RUBY_V34_PLUS = Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('3.4')
+end

data/lib/mocha/sequence.rb

@@ -1,42 +1,48 @@
-module Mocha # :nodoc:
-  
+# frozen_string_literal: true
+
+module Mocha
+  # Used to constrain the order in which expectations can occur.
+  #
+  # @see API#sequence
+  # @see Expectation#in_sequence
   class Sequence
-    
+    # @private
     class InSequenceOrderingConstraint
-      
       def initialize(sequence, index)
-        @sequence, @index = sequence, index
+        @sequence = sequence
+        @index = index
       end
-      
+
       def allows_invocation_now?
         @sequence.satisfied_to_index?(@index)
       end
-      
+
       def mocha_inspect
         "in sequence #{@sequence.mocha_inspect}"
       end
-      
     end
-    
+
+    # @private
     def initialize(name)
       @name = name
       @expectations = []
     end
-    
+
+    # @private
     def constrain_as_next_in_sequence(expectation)
       index = @expectations.length
       @expectations << expectation
       expectation.add_ordering_constraint(InSequenceOrderingConstraint.new(self, index))
     end
-    
+
+    # @private
     def satisfied_to_index?(index)
-      @expectations[0...index].all? { |expectation| expectation.satisfied? }
+      @expectations[0...index].all?(&:satisfied?)
     end
-    
+
+    # @private
     def mocha_inspect
-      "#{@name.mocha_inspect}"
+      @name.mocha_inspect.to_s
     end
-    
   end
-  
-end
+end

data/lib/mocha/single_return_value.rb

@@ -1,24 +1,14 @@
-require 'mocha/is_a'
-require 'mocha/deprecation'
+# frozen_string_literal: true
 
-module Mocha # :nodoc:
-  
-  class SingleReturnValue # :nodoc:
-    
+module Mocha
+  class SingleReturnValue
     def initialize(value)
       @value = value
     end
-    
-    def evaluate
-      if @value.__is_a__(Proc) then
-        message = 'use of Expectation#returns with instance of Proc - see Expectation#returns RDoc for alternatives'
-        Deprecation.warning(message)
-        @value.call
-      else
-        @value
-      end
+
+    def evaluate(invocation)
+      invocation.returned(@value)
+      @value
     end
-    
   end
-  
-end
+end

data/lib/mocha/state_machine.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Mocha
+  # A state machine that is used to constrain the order of invocations.
+  # An invocation can be constrained to occur when a state {#is}, or {#is_not}, active.
+  class StateMachine
+    # Provides the ability to determine whether a {StateMachine} is in a specified state at some point in the future.
+    class StatePredicate
+      # @private
+      def initialize(state_machine, state, description, &active_check)
+        @state_machine = state_machine
+        @state = state
+        @description = description
+        @active_check = active_check
+      end
+
+      # @private
+      def active?
+        @active_check.call(@state_machine.current_state, @state)
+      end
+
+      # @private
+      def mocha_inspect
+        "#{@state_machine.name} #{@description} #{@state.mocha_inspect}"
+      end
+    end
+
+    # Provides a mechanism to change the state of a {StateMachine} at some point in the future.
+    class State < StatePredicate
+      # @private
+      def activate
+        @state_machine.current_state = @state
+      end
+    end
+
+    # @private
+    attr_reader :name
+
+    # @private
+    attr_accessor :current_state
+
+    # @private
+    def initialize(name)
+      @name = name
+      @current_state = nil
+    end
+
+    # Put the {StateMachine} into the state specified by +initial_state_name+.
+    #
+    # @param [String] initial_state_name name of initial state
+    # @return [StateMachine] state machine, thereby allowing invocations of other {StateMachine} methods to be chained.
+    def starts_as(initial_state_name)
+      become(initial_state_name)
+      self
+    end
+
+    # Put the {StateMachine} into the +next_state_name+.
+    #
+    # @param [String] next_state_name name of new state
+    def become(next_state_name)
+      @current_state = next_state_name
+    end
+
+    # Provides mechanisms to (a) determine whether the {StateMachine} is in a given state; or (b) to change the {StateMachine} into the given state.
+    #
+    # @param [String] state_name name of expected/desired state.
+    # @return [StatePredicate,State] (a) state predicate which, when queried, will indicate whether the {StateMachine} is in the given state; or (b) state which, when activated, will change the {StateMachine} into the given state.
+    #
+    # @overload def is(expected_state_name)
+    #   Provides a mechanism to determine whether the {StateMachine} is in the state specified by +expected_state_name+ at some point in the future
+    #   @param [String] expected_state_name name of expected state.
+    #   @return [StatePredicate] state predicate which, when queried, will indicate whether the {StateMachine} is in the state specified by +expected_state_name+
+    #
+    # @overload def is(desired_state_name)
+    #   Provides a mechanism to change the {StateMachine} into the state specified by +desired_state_name+ at some point in the future.
+    #   @param [String] desired_state_name name of desired new state.
+    #   @return [State] state which, when activated, will change the {StateMachine} into the state with the specified +desired_state_name+.
+    def is(state_name)
+      State.new(self, state_name, 'is') { |current, given| current == given }
+    end
+
+    # Provides a mechanism to determine whether the {StateMachine} is *not* in the state specified by +unexpected_state_name+ at some point in the future.
+    #
+    # @param [String] unexpected_state_name name of unexpected state.
+    # @return [StatePredicate] state predicate which, when queried, will indicate whether the {StateMachine} is *not* in the state specified by +unexpected_state_name+.
+    def is_not(unexpected_state_name) # rubocop:disable Naming/PredicatePrefix
+      StatePredicate.new(self, unexpected_state_name, 'is not') { |current, given| current != given }
+    end
+
+    # @private
+    def mocha_inspect
+      %(#{@name} #{@current_state ? "is #{@current_state.mocha_inspect}" : 'has no current state'})
+    end
+  end
+end