Class | Mocha::Mock |
In: |
lib/mocha/mock.rb
|
Parent: | Object |
Traditional mock object.
All methods return an {Expectation} which can be further modified by methods on {Expectation}.
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:
However, there are some possible "gotchas" caused by this scheme:
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).
@example
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
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.
everything_stubbed | [R] | @private |
Adds an expectation that the specified method must be called exactly once with any parameters.
@param [Symbol,String] method_name name of expected method @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 {expects} were called multiple times.
@overload def expects(method_name) @overload def expects(expected_methods_vs_return_values) @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
@example Expected method invoked once so no error raised
object = mock() object.expects(:expected_method) object.expected_method
@example 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
@example 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
@example 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)
Constrains the {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 {Mock} instance will delegate its +respond_to?+ method to the responder.
Note that the methods on responder are never actually invoked.
@param [Object, respond_to?] responder an object used to determine whether {Mock} instance should +respond_to?+ to an invocation. @return [Mock] the same {Mock} instance, thereby allowing invocations of other {Mock} methods to be chained. @see responds_like_instance_of
@example 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
@example 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
@example 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
Constrains the {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 {Mock} instance will delegate its +respond_to?+ method to the responder instance.
Note that the methods on the responder instance are never actually invoked.
@param [Class] responder_class a class used to determine whether {Mock} instance should +respond_to?+ to an invocation. @return [Mock] the same {Mock} instance, thereby allowing invocations of other {Mock} methods to be chained. @see responds_like
@example 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
Adds an expectation that the specified method may be called any number of times with any parameters.
@param [Symbol,String] method_name name of stubbed method @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 {stubs} were called multiple times.
@overload def stubs(method_name) @overload def stubs(stubbed_methods_vs_return_values) @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
@example 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
@example 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)
Removes the specified stubbed method (added by calls to {expects} or {stubs}) and all expectations associated with it.
@param [Symbol] method_name name of method to unstub.
@example 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()