mocha 0.10.5 → 1.13.0

data/lib/mocha/api.rb

@@ -1,173 +1,241 @@
 require 'mocha/parameter_matchers'
+require 'mocha/hooks'
 require 'mocha/mockery'
 require 'mocha/sequence'
+require 'mocha/object_methods'
+require 'mocha/class_methods'
 
-module Mocha # :nodoc:
-  
-  # Methods added to Test::Unit::TestCase or equivalent.
+module Mocha
+  # Methods added to +Test::Unit::TestCase+, +MiniTest::Unit::TestCase+ or equivalent.
+  # The mock creation methods are {#mock}, {#stub} and {#stub_everything}, all of which return a #{Mock}
+  # which can be further modified by {Mock#responds_like} and {Mock#responds_like_instance_of} methods,
+  # both of which return a {Mock}, too, and can therefore, be chained to the original creation methods.
+  #
+  # {Mock#responds_like} and {Mock#responds_like_instance_of} force the mock to indicate what it is
+  # supposed to be mocking, thus making it a safer verifying mock. They check that the underlying +responder+
+  # will actually respond to the methods being stubbed, throwing a +NoMethodError+ upon invocation otherwise.
+  #
+  # @example Verifying mock using {Mock#responds_like_instance_of}
+  #   class Sheep
+  #     def initialize
+  #       raise "some awkward code we don't want to call"
+  #     end
+  #     def chew(grass); end
+  #   end
+  #
+  #   sheep = mock('sheep').responds_like_instance_of(Sheep)
+  #   sheep.expects(:chew)
+  #   sheep.expects(:foo)
+  #   sheep.respond_to?(:chew) # => true
+  #   sheep.respond_to?(:foo) # => false
+  #   sheep.chew
+  #   sheep.foo # => raises NoMethodError exception
   module API
-    
     include ParameterMatchers
-    
-    # :call-seq: mock(name, &block) -> mock object
-    #            mock(expected_methods = {}, &block) -> mock object
-    #            mock(name, expected_methods = {}, &block) -> mock object
-    #
-    # Creates a mock object.
-    #
-    # +name+ is a +String+ identifier for the mock object.
-    #
-    # +expected_methods+ is a +Hash+ with expected method name symbols as keys and corresponding return values as values.
-    #
-    # Note that (contrary to expectations set up by #stub) these expectations <b>must</b> be fulfilled during the test.
-    #   def test_product
-    #     product = mock('ipod_product', :manufacturer => 'ipod', :price => 100)
-    #     assert_equal 'ipod', product.manufacturer
-    #     assert_equal 100, product.price
-    #     # an error will be raised unless both Product#manufacturer and Product#price have been called
-    #   end 
-    #
-    # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
-    #   def test_product
-    #     product = mock('ipod_product') do
-    #       expects(:manufacturer).returns('ipod')
-    #       expects(:price).returns(100)
-    #     end
-    #     assert_equal 'ipod', product.manufacturer
-    #     assert_equal 100, product.price
-    #     # an error will be raised unless both Product#manufacturer and Product#price have been called
-    #   end 
-    def mock(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    include Hooks
+
+    # @private
+    def self.included(_mod)
+      Object.send(:include, Mocha::ObjectMethods)
+      Class.send(:include, Mocha::ClassMethods)
+    end
+
+    # @private
+    def self.extended(mod)
+      included(mod)
+    end
+
+    # Builds a new mock object
+    #
+    # @return [Mock] a new mock object
+    #
+    # @overload def mock(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that expected the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def mock(expected_methods_vs_return_values = {})
+    #   @param [Hash] expected_methods_vs_return_values expected method name symbols as keys and corresponding return values as values - these expectations are setup as if {Mock#expects} were called multiple times.
+    # @overload def mock(name, expected_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @param [Hash] expected_methods_vs_return_values expected method name symbols as keys and corresponding return values as values - these expectations are setup as if {Mock#expects} were called multiple times.
+    #
+    # @example Using expected_methods_vs_return_values Hash to setup expectations.
+    #   def test_motor_starts_and_stops
+    #     motor = mock('motor', :start => true, :stop => true)
+    #     assert motor.start
+    #     assert motor.stop
+    #     # an error will be raised unless both Motor#start and Motor#stop have been called
+    #   end
+    #
+    def mock(*arguments) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of expected methods vs return values,",
+            " e.g. `mock(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `mock(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of expected methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      mock = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      mock = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       mock.expects(expectations)
       mock
     end
-    
-    # :call-seq: stub(name, &block) -> mock object
-    #            stub(stubbed_methods = {}, &block) -> mock object
-    #            stub(name, stubbed_methods = {}, &block) -> mock object
-    #
-    # Creates a mock object.
-    #
-    # +name+ is a +String+ identifier for the mock object.
-    #
-    # +stubbed_methods+ is a +Hash+ with stubbed method name symbols as keys and corresponding return values as values.
-    # Note that (contrary to expectations set up by #mock) these expectations <b>need not</b> be fulfilled during the test.
-    #   def test_product
-    #     product = stub('ipod_product', :manufacturer => 'ipod', :price => 100)
-    #     assert_equal 'ipod', product.manufacturer
-    #     assert_equal 100, product.price
-    #     # an error will not be raised even if Product#manufacturer and Product#price have not been called
-    #   end
-    #
-    # +block+ is an optional block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
-    #   def test_product
-    #     product = stub('ipod_product') do
-    #       stubs(:manufacturer).returns('ipod')
-    #       stubs(:price).returns(100)
-    #     end
-    #     assert_equal 'ipod', product.manufacturer
-    #     assert_equal 100, product.price
-    #     # an error will not be raised even if Product#manufacturer and Product#price have not been called
+
+    # Builds a new mock object
+    #
+    # @return [Mock] a new mock object
+    #
+    # @overload def stub(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that stubbed the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def stub(stubbed_methods_vs_return_values = {})
+    #   @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {Mock#stubs} were called multiple times.
+    # @overload def stub(name, stubbed_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #
+    # @example Using stubbed_methods_vs_return_values Hash to setup stubbed methods.
+    #   def test_motor_starts_and_stops
+    #     motor = stub('motor', :start => true, :stop => true)
+    #     assert motor.start
+    #     assert motor.stop
+    #     # an error will not be raised even if either Motor#start or Motor#stop has not been called
     #   end
-    def stub(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def stub(*arguments)
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of stubbed methods vs return values,",
+            " e.g. `stub(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `stub(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of stubbed methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      stub = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      stub = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       stub.stubs(expectations)
       stub
     end
-    
-    # :call-seq: stub_everything(name, &block) -> mock object
-    #            stub_everything(stubbed_methods = {}, &block) -> mock object
-    #            stub_everything(name, stubbed_methods = {}, &block) -> mock object
-    #
-    # Creates a mock object that accepts calls to any method.
-    #
-    # By default it will return +nil+ for any method call.
-    #
-    # +block+ is a block to be evaluated against the mock object instance, giving an alernative way to set up expectations & stubs.
-    #
-    # +name+ and +stubbed_methods+ work in the same way as for #stub.
-    #   def test_product
-    #     product = stub_everything('ipod_product', :price => 100)
-    #     assert_nil product.manufacturer
-    #     assert_nil product.any_old_method
-    #     assert_equal 100, product.price
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    # Builds a mock object that accepts calls to any method. By default it will return +nil+ for any method call.
+    #
+    # @return [Mock] a new mock object
+    #
+    # @overload def stub_everything(name)
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @note Prior to v1.10.0 when +name+ was a +Symbol+, this method returned an unnamed +Mock+ that stubbed the method identified by +name+. This was undocumented behaviour and it will be removed in the future, but for the moment it can be reinstated using {Configuration#reinstate_undocumented_behaviour_from_v1_9=}.
+    # @overload def stub_everything(stubbed_methods_vs_return_values = {})
+    #   @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {Mock#stubs} were called multiple times.
+    # @overload def stub_everything(name, stubbed_methods_vs_return_values = {})
+    #   @param [String, Symbol] name identifies mock object in error messages.
+    #   @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {Mock#stubs} were called multiple times.
+    #
+    # @example Ignore invocations of irrelevant methods.
+    #   def test_motor_stops
+    #     motor = stub_everything('motor', :stop => true)
+    #     assert_nil motor.irrelevant_method_1 # => no error raised
+    #     assert_nil motor.irrelevant_method_2 # => no error raised
+    #     assert motor.stop
     #   end
-    def stub_everything(*arguments, &block)
-      name = arguments.shift if arguments.first.is_a?(String)
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def stub_everything(*arguments)
+      if Mocha.configuration.reinstate_undocumented_behaviour_from_v1_9?
+        if arguments.first.is_a?(Symbol)
+          method_name = arguments[0]
+          Deprecation.warning(
+            "Explicitly include `#{method_name}` in Hash of stubbed methods vs return values,",
+            " e.g. `stub_everything(:#{method_name} => nil)`."
+          )
+          if arguments[1]
+            Deprecation.warning(
+              "In this case the 2nd argument for `stub_everything(:##{method_name}, ...)` is ignored,",
+              ' but in the future a Hash of stubbed methods vs return values will be respected.'
+            )
+          end
+        elsif arguments.first.is_a?(String)
+          name = arguments.shift
+        end
+      elsif arguments.first.is_a?(String) || arguments.first.is_a?(Symbol)
+        name = arguments.shift
+      end
       expectations = arguments.shift || {}
-      stub = name ? Mockery.instance.named_mock(name, &block) : Mockery.instance.unnamed_mock(&block)
+      stub = name ? Mockery.instance.named_mock(name) : Mockery.instance.unnamed_mock
       stub.stub_everything
       stub.stubs(expectations)
       stub
     end
-    
-    # :call-seq: sequence(name) -> sequence
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    # Builds a new sequence which can be used to constrain the order in which expectations can occur.
+    #
+    # Specify that an expected invocation must occur within a named {Sequence} by using {Expectation#in_sequence}.
     #
-    # Returns a new sequence that is used to constrain the order in which expectations can occur.
+    # @return [Sequence] a new sequence
     #
-    # Specify that an expected invocation must occur in within a named +sequence+ by using Expectation#in_sequence.
+    # @see Expectation#in_sequence
     #
-    # See also Expectation#in_sequence.
+    # @example Ensure methods on egg are invoked in correct order.
     #   breakfast = sequence('breakfast')
     #
-    #   egg = mock('egg')
-    #   egg.expects(:crack).in_sequence(breakfast)
-    #   egg.expects(:fry).in_sequence(breakfast)
-    #   egg.expects(:eat).in_sequence(breakfast)
+    #   egg = mock('egg') do
+    #     expects(:crack).in_sequence(breakfast)
+    #     expects(:fry).in_sequence(breakfast)
+    #     expects(:eat).in_sequence(breakfast)
+    #   end
     def sequence(name)
       Sequence.new(name)
     end
-    
-    # :call-seq: states(name) -> state_machine
+
+    # Builds a new state machine which can be used to constrain the order in which expectations can occur.
     #
-    # Returns a new +state_machine+ that is used to constrain the order in which expectations can occur.
+    # Specify the initial state of the state machine by using {StateMachine#starts_as}.
     #
-    # Specify the initial +state+ of the +state_machine+ by using StateMachine#starts_as.
+    # Specify that an expected invocation should change the state of the state machine by using {Expectation#then}.
     #
-    # Specify that an expected invocation should change the +state+ of the +state_machine+ by using Expectation#then.
+    # Specify that an expected invocation should be constrained to occur within a particular +state+ by using {Expectation#when}.
     #
-    # Specify that an expected invocation should be constrained to occur within a particular +state+ by using Expectation#when.
+    # A test can contain multiple state machines.
     #
-    # A test can contain multiple +state_machines+.
+    # @return [StateMachine] a new state machine
     #
-    # See also Expectation#then, Expectation#when and StateMachine.
+    # @see Expectation#then
+    # @see Expectation#when
+    # @see StateMachine
+    # @example Constrain expected invocations to occur in particular states.
     #   power = states('power').starts_as('off')
     #
-    #   radio = mock('radio')
-    #   radio.expects(:switch_on).then(power.is('on'))
-    #   radio.expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
-    #   radio.expects(:adjust_volume).with(+5).when(power.is('on'))
-    #   radio.expects(:select_channel).with('BBC World Service').when(power.is('on'))
-    #   radio.expects(:adjust_volume).with(-5).when(power.is('on'))
-    #   radio.expects(:switch_off).then(power.is('off'))
+    #   radio = mock('radio') do
+    #     expects(:switch_on).then(power.is('on'))
+    #     expects(:select_channel).with('BBC Radio 4').when(power.is('on'))
+    #     expects(:adjust_volume).with(+5).when(power.is('on'))
+    #     expects(:select_channel).with('BBC World Service').when(power.is('on'))
+    #     expects(:adjust_volume).with(-5).when(power.is('on'))
+    #     expects(:switch_off).then(power.is('off'))
+    #   end
     def states(name)
       Mockery.instance.new_state_machine(name)
     end
-    
-    def mocha_setup # :nodoc:
-    end
-    
-    def mocha_verify(assertion_counter = nil) # :nodoc:
-      Mockery.instance.verify(assertion_counter)
-    end
-    
-    def mocha_teardown # :nodoc:
-      Mockery.instance.teardown
-      Mockery.reset_instance
-    end
-    
-  end
-  
-  def self.const_missing(name)
-    return super unless name == :Standalone
-    require 'mocha/deprecation'
-    Deprecation.warning "Mocha::Standalone has been renamed to Mocha::API"
-    return API
   end
-  
 end

data/lib/mocha/argument_iterator.rb

@@ -1,21 +1,17 @@
 module Mocha
-  
   class ArgumentIterator
-  
     def initialize(argument)
       @argument = argument
     end
-  
-    def each(&block)
-      if @argument.is_a?(Hash) then
+
+    def each
+      if @argument.is_a?(Hash)
         @argument.each do |method_name, return_value|
-          block.call(method_name, return_value)
+          yield method_name, return_value
         end
       else
-        block.call(@argument)
+        yield @argument
       end
     end
-  
   end
-  
-end
+end

data/lib/mocha/backtrace_filter.rb

@@ -1,8 +1,6 @@
 module Mocha
-
   class BacktraceFilter
-  
-    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), "..")) + File::SEPARATOR
+    LIB_DIRECTORY = File.expand_path(File.join(File.dirname(__FILE__), '..')) + File::SEPARATOR
 
     def initialize(lib_directory = LIB_DIRECTORY)
       @path_pattern = Regexp.new(lib_directory)
@@ -11,7 +9,5 @@ module Mocha
     def filtered(backtrace)
       backtrace.reject { |location| @path_pattern.match(File.expand_path(location)) }
     end
-
   end
-
 end

data/lib/mocha/block_matcher.rb

@@ -0,0 +1,31 @@
+module Mocha
+  module BlockMatchers
+    class OptionalBlock
+      def match?(_actual_block)
+        true
+      end
+
+      def mocha_inspect; end
+    end
+
+    class BlockGiven
+      def match?(actual_block)
+        !actual_block.nil?
+      end
+
+      def mocha_inspect
+        'with block given'
+      end
+    end
+
+    class NoBlockGiven
+      def match?(actual_block)
+        actual_block.nil?
+      end
+
+      def mocha_inspect
+        'with no block given'
+      end
+    end
+  end
+end

data/lib/mocha/cardinality.rb

@@ -1,95 +1,106 @@
 module Mocha
-
   class Cardinality
-    
     INFINITY = 1 / 0.0
-    
-    class << self
-      
-      def exactly(count)
-        new(count, count)
-      end
-      
-      def at_least(count)
-        new(count, INFINITY)
-      end
-      
-      def at_most(count)
-        new(0, count)
-      end
-      
-      def times(range_or_count)
-        case range_or_count
-          when Range then new(range_or_count.first, range_or_count.last)
-          else new(range_or_count, range_or_count)
-        end
+
+    def initialize(required = 0, maximum = INFINITY)
+      update(required, maximum)
+      @invocations = []
+    end
+
+    def exactly(count)
+      update(count, count)
+    end
+
+    def at_least(count)
+      update(count, INFINITY)
+    end
+
+    def at_most(count)
+      update(0, count)
+    end
+
+    def times(range_or_count)
+      case range_or_count
+      when Range then update(range_or_count.first, range_or_count.last)
+      else update(range_or_count, range_or_count)
       end
-      
     end
-    
-    def initialize(required, maximum)
-      @required, @maximum = required, maximum
+
+    def <<(invocation)
+      @invocations << invocation
     end
-    
-    def invocations_allowed?(invocation_count)
-      invocation_count < maximum
+
+    def invocations_allowed?
+      @invocations.size < maximum
     end
-    
-    def satisfied?(invocations_so_far)
-      invocations_so_far >= required
+
+    def satisfied?
+      @invocations.size >= required
     end
-    
+
     def needs_verifying?
       !allowed_any_number_of_times?
     end
-    
-    def verified?(invocation_count)
-      (invocation_count >= required) && (invocation_count <= maximum)
+
+    def verified?
+      (@invocations.size >= required) && (@invocations.size <= maximum)
     end
-    
+
     def allowed_any_number_of_times?
-      required == 0 && infinite?(maximum)
+      required.zero? && infinite?(maximum)
     end
-    
-    def used?(invocation_count)
-      (invocation_count > 0) || (maximum == 0)
+
+    def used?
+      @invocations.any? || maximum.zero?
     end
-    
-    def mocha_inspect
+
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def anticipated_times
       if allowed_any_number_of_times?
-        "allowed any number of times"
+        'allowed any number of times'
+      elsif required.zero? && maximum.zero?
+        "expected #{count(maximum)}"
+      elsif required == maximum
+        "expected exactly #{count(required)}"
+      elsif infinite?(maximum)
+        "expected at least #{count(required)}"
+      elsif required.zero?
+        "expected at most #{count(maximum)}"
       else
-        if required == 0 && maximum == 0
-          "expected never"
-        elsif required == maximum
-          "expected exactly #{times(required)}"
-        elsif infinite?(maximum)
-          "expected at least #{times(required)}"
-        elsif required == 0
-          "expected at most #{times(maximum)}"
-        else
-          "expected between #{required} and #{times(maximum)}"
-        end
+        "expected between #{required} and #{count(maximum)}"
       end
     end
-    
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    def invoked_times
+      "invoked #{count(@invocations.size)}"
+    end
+
+    def actual_invocations
+      @invocations.map(&:full_description).join
+    end
+
     protected
-    
+
     attr_reader :required, :maximum
-    
-    def times(number)
+
+    def count(number)
       case number
-        when 0 then "no times"
-        when 1 then "once"
-        when 2 then "twice"
-        else "#{number} times"
+      when 0 then 'never'
+      when 1 then 'once'
+      when 2 then 'twice'
+      else "#{number} times"
       end
     end
-    
+
+    def update(required, maximum)
+      @required = required
+      @maximum = maximum
+      self
+    end
+
     def infinite?(number)
       number.respond_to?(:infinite?) && number.infinite?
     end
-    
   end
-  
 end