# Class: Mocha::Mock

Inherits:
  Object
  - Object
  - Mocha::Mock
  show all

Defined in:
  lib/mocha/mock.rb

## Overview

Traditional mock object.

#expects and #stubs return an Expectation which can be further modified by methods on Expectation.

#responds_like and #responds_like_instance_of both return a Mock, and can therefore, be chained to the original creation methods in API. They 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.

Stubs and expectations are basically the same thing. A stub is just an expectation of zero or more invocations. The #stubs method is syntactic sugar to make the intent of the test more explicit.

When a method is invoked on a mock object, the mock object searches through its expectations from newest to oldest to find one that matches the invocation. After the invocation, the matching expectation might stop matching further invocations. For example, an `expects(:foo).once` expectation only matches once and will be ignored on future invocations while an `expects(:foo).at_least_once` expectation will always be matched against invocations.

This scheme allows you to:

- Set up default stubs in your the `setup` method of your test class and override some of those stubs in individual tests.

- Set up different `once` expectations for the same method with different action per invocation. However, it's better to use the Expectation#returns method with multiple arguments to do this, as described below.

However, there are some possible “gotchas” caused by this scheme:

- if you create an expectation and then a stub for the same method, the stub will always override the expectation and the expectation will never be met.

- if you create a stub and then an expectation for the same method, the expectation will match, and when it stops matching the stub will be used instead, possibly masking test failures.

- if you create different expectations for the same method, they will be invoked in the opposite order than that in which they were specified, rather than the same order.

The best thing to do is not set up multiple expectations and stubs for the same method with exactly the same matchers. Instead, use the Expectation#returns method with multiple arguments to create multiple actions for a method. You can also chain multiple calls to Expectation#returns and Expectation#raises (along with syntactic sugar Expectation#then if desired).

If you want to specify more complex ordering or order invocations across different mock objects, use the Expectation#in_sequence method to explicitly define a total or partial ordering of invocations.

Examples:

    object = mock()
    object.stubs(:expected_method).returns(1, 2).then.raises(Exception)
    object.expected_method # => 1
    object.expected_method # => 2
    object.expected_method # => raises exception of class Exception1

## Instance Method Summary collapse

- #expects(method_name_or_hash, backtrace = nil) ⇒ Expectation (also: #__expects__)

  Adds an expectation that the specified method must be called exactly once with any parameters.

- #responds_like(responder) ⇒ Mock (also: #quacks_like)

  Constrains the Mock instance so that it can only expect or stub methods to which `responder` responds.

- #responds_like_instance_of(responder_class) ⇒ Mock (also: #quacks_like_instance_of)

  Constrains the Mock instance so that it can only expect or stub methods to which an instance of the `responder_class` responds.

- #stubs(method_name_or_hash, backtrace = nil) ⇒ Expectation (also: #__stubs__)

  Adds an expectation that the specified method may be called any number of times with any parameters.

- #unstub(*method_names) ⇒ Object

  Removes the specified stubbed methods (added by calls to #expects or #stubs) and all expectations associated with them.

## Dynamic Method Handling

This class handles dynamic methods through the `method_missing` method

### #method_missing(symbol, *arguments, &block) ⇒ `Object`

    313
    314
    315
    316
    317
    318
    319
    320
    321
    322

    # File 'lib/mocha/mock.rb', line 313

    def method_missing(symbol, *arguments, &block) # rubocop:disable Style/MethodMissingSuper
      check_expiry
      check_responder_responds_to(symbol)
      invocation = Invocation.new(self, symbol, *arguments, &block)
      if (matching_expectation_allowing_invocation = all_expectations.match_allowing_invocation(invocation))
        matching_expectation_allowing_invocation.invoke(invocation)
      elsif (matching_expectation = all_expectations.match(invocation)) || (!matching_expectation && !@everything_stubbed)
        raise_unexpected_invocation_error(invocation, matching_expectation)
      end
    end

## Instance Method Details

### #expects(method_name) ⇒ `Expectation` #expects(expected_methods_vs_return_values) ⇒ `Expectation` Also known as: __expects__

Adds an expectation that the specified method must be called exactly once with any parameters.

Examples:

Expected method invoked once so no error raised

    object = mock()
    object.expects(:expected_method)
    object.expected_method

Expected method not invoked so error raised

    object = mock()
    object.expects(:expected_method)
    # error raised when test completes, because expected_method not called exactly once

Expected method invoked twice so error raised

    object = mock()
    object.expects(:expected_method)
    object.expected_method
    object.expected_method # => error raised when expected method invoked second time

Setup multiple expectations using `expected_methods_vs_return_values`.

    object = mock()
    object.expects(:expected_method_one => :result_one, :expected_method_two => :result_two)

    # is exactly equivalent to

    object = mock()
    object.expects(:expected_method_one).returns(:result_one)
    object.expects(:expected_method_two).returns(:result_two)

Overloads:

- #expects(method_name) ⇒ `Expectation`

  Parameters:

  - method_name (`Symbol`, `String`) —

    name of expected method

- #expects(expected_methods_vs_return_values) ⇒ `Expectation`

  Parameters:

  - expected_methods_vs_return_values (`Hash`) —

    expected method name symbols as keys and corresponding return values as values - these expectations are setup as if #expects were called multiple times.

Returns:

- (`Expectation`) —

  last-built expectation which can be further modified by methods on Expectation.

    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122

    # File 'lib/mocha/mock.rb', line 111

    def expects(method_name_or_hash, backtrace = nil)
      expectation = nil
      iterator = ArgumentIterator.new(method_name_or_hash)
      iterator.each do |*args|
        method_name = args.shift
        ensure_method_not_already_defined(method_name)
        expectation = Expectation.new(self, method_name, backtrace)
        expectation.returns(args.shift) unless args.empty?
        @expectations.add(expectation)
      end
      expectation
    end

### #responds_like(responder) ⇒ `Mock` Also known as: quacks_like

Constrains the Mocha::Mock instance so that it can only expect or stub methods to which `responder` responds. The constraint is only applied at method invocation time.

A `NoMethodError` will be raised if the `responder` does not `#respond_to?` a method invocation (even if the method has been expected or stubbed).

The Mocha::Mock instance will delegate its `#respond_to?` method to the `responder`.

Note that the methods on `responder` are never actually invoked.

Examples:

Normal mocking

    sheep = mock('sheep')
    sheep.expects(:chew)
    sheep.expects(:foo)
    sheep.respond_to?(:chew) # => true
    sheep.respond_to?(:foo) # => true
    sheep.chew
    sheep.foo
    # no error raised

Using #responds_like with an instance method

    class Sheep
      def chew(grass); end
    end

    sheep = mock('sheep')
    sheep.responds_like(Sheep.new)
    sheep.expects(:chew)
    sheep.expects(:foo)
    sheep.respond_to?(:chew) # => true
    sheep.respond_to?(:foo) # => false
    sheep.chew
    sheep.foo # => raises NoMethodError exception

Using #responds_like with a class method

    class Sheep
      def self.number_of_legs; end
    end

    sheep_class = mock('sheep_class')
    sheep_class.responds_like(Sheep)
    sheep_class.stubs(:number_of_legs).returns(4)
    sheep_class.expects(:foo)
    sheep_class.respond_to?(:number_of_legs) # => true
    sheep_class.respond_to?(:foo) # => false
    sheep_class.number_of_legs # => 4
    sheep_class.foo # => raises NoMethodError exception

Parameters:

- responder (`Object`, `#respond_to?`) —

  an object used to determine whether Mocha::Mock instance should `#respond_to?` to an invocation.

Returns:

- (`Mock`) —

  the same Mocha::Mock instance, thereby allowing invocations of other Mocha::Mock methods to be chained.

See Also:

- #responds_like_instance_of

    236
    237
    238
    239

    # File 'lib/mocha/mock.rb', line 236

    def responds_like(responder)
      @responder = responder
      self
    end

### #responds_like_instance_of(responder_class) ⇒ `Mock` Also known as: quacks_like_instance_of

Constrains the Mocha::Mock instance so that it can only expect or stub methods to which an instance of the `responder_class` responds. The constraint is only applied at method invocation time. Note that the responder instance is instantiated using `Class#allocate`.

A `NoMethodError` will be raised if the responder instance does not `#respond_to?` a method invocation (even if the method has been expected or stubbed).

The Mocha::Mock instance will delegate its `#respond_to?` method to the responder instance.

Note that the methods on the responder instance are never actually invoked.

Examples:

Using #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')
    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

Parameters:

- responder_class (`Class`) —

  a class used to determine whether Mocha::Mock instance should `#respond_to?` to an invocation.

Returns:

- (`Mock`) —

  the same Mocha::Mock instance, thereby allowing invocations of other Mocha::Mock methods to be chained.

See Also:

- #responds_like

    269
    270
    271

    # File 'lib/mocha/mock.rb', line 269

    def responds_like_instance_of(responder_class)
      responds_like(responder_class.allocate)
    end

### #stubs(method_name) ⇒ `Expectation` #stubs(stubbed_methods_vs_return_values) ⇒ `Expectation` Also known as: __stubs__

Adds an expectation that the specified method may be called any number of times with any parameters.

Examples:

No error raised however many times stubbed method is invoked

    object = mock()
    object.stubs(:stubbed_method)
    object.stubbed_method
    object.stubbed_method
    # no error raised

Setup multiple expectations using `stubbed_methods_vs_return_values`.

    object = mock()
    object.stubs(:stubbed_method_one => :result_one, :stubbed_method_two => :result_two)

    # is exactly equivalent to

    object = mock()
    object.stubs(:stubbed_method_one).returns(:result_one)
    object.stubs(:stubbed_method_two).returns(:result_two)

Overloads:

- #stubs(method_name) ⇒ `Expectation`

  Parameters:

  - method_name (`Symbol`, `String`) —

    name of stubbed method

- #stubs(stubbed_methods_vs_return_values) ⇒ `Expectation`

  Parameters:

  - stubbed_methods_vs_return_values (`Hash`) —

    stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if #stubs were called multiple times.

Returns:

- (`Expectation`) —

  last-built expectation which can be further modified by methods on Expectation.

    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161

    # File 'lib/mocha/mock.rb', line 149

    def stubs(method_name_or_hash, backtrace = nil)
      expectation = nil
      iterator = ArgumentIterator.new(method_name_or_hash)
      iterator.each do |*args|
        method_name = args.shift
        ensure_method_not_already_defined(method_name)
        expectation = Expectation.new(self, method_name, backtrace)
        expectation.at_least(0)
        expectation.returns(args.shift) unless args.empty?
        @expectations.add(expectation)
      end
      expectation
    end

### #unstub(*method_names) ⇒ `Object`

Removes the specified stubbed methods (added by calls to #expects or #stubs) and all expectations associated with them.

Examples:

Invoking an unstubbed method causes error to be raised

    object = mock('mock') do
    object.stubs(:stubbed_method).returns(:result_one)
    object.stubbed_method # => :result_one
    object.unstub(:stubbed_method)
    object.stubbed_method # => unexpected invocation: #<Mock:mock>.stubbed_method()

Unstubbing multiple methods.

    multiplier.unstub(:double, :triple)

    # exactly equivalent to

    multiplier.unstub(:double)
    multiplier.unstub(:triple)

Parameters:

- method_names (`Array<Symbol>`) —

  names of methods to unstub.

    181
    182
    183
    184
    185

    # File 'lib/mocha/mock.rb', line 181

    def unstub(*method_names)
      method_names.each do |method_name|
        @expectations.remove_all_matching_method(method_name)
      end
    end