class Mocha::Expectation
Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
def add_in_sequence_ordering_constraint(sequence)
- Private: -
def add_in_sequence_ordering_constraint(sequence) sequence.constrain_as_next_in_sequence(self) end
def add_ordering_constraint(ordering_constraint)
- Private: -
def add_ordering_constraint(ordering_constraint) @ordering_constraints << ordering_constraint end
def add_side_effect(side_effect)
- Private: -
def add_side_effect(side_effect) @side_effects << side_effect end
def at_least(minimum_number_of_times)
- Example: Expected method must be called at least twice. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
minimum_number_of_times(Integer) -- minimum number of expected invocations.
def at_least(minimum_number_of_times) @cardinality.at_least(minimum_number_of_times) self end
def at_least_once
- Example: Expected method must be called at least once. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def at_least_once at_least(1) end
def at_most(maximum_number_of_times)
- Example: Expected method must be called at most twice. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
maximum_number_of_times(Integer) -- maximum number of expected invocations.
def at_most(maximum_number_of_times) @cardinality.at_most(maximum_number_of_times) self end
def at_most_once
- Example: Expected method must be called at most once. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def at_most_once at_most(1) end
def definition_location
- Private: -
def definition_location filter = BacktraceFilter.new filter.filtered(backtrace)[0] end
def in_correct_order?
- Private: -
def in_correct_order? @ordering_constraints.all?(&:allows_invocation_now?) end
def in_sequence(sequence, *sequences)
- Example: Ensure methods are invoked in a specified order. -
Other tags:
- See: API#sequence -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
sequences(*Array) -- more sequences in which expected method should appear. -
sequence(Sequence) -- sequence in which expected method should appear.
def in_sequence(sequence, *sequences) sequences.unshift(sequence).each { |seq| add_in_sequence_ordering_constraint(seq) } self end
def initialize(mock, expected_method_name, backtrace = nil)
- Private: -
def initialize(mock, expected_method_name, backtrace = nil) @mock = mock @method_matcher = MethodMatcher.new(expected_method_name.to_sym) @parameters_matcher = ParametersMatcher.new @block_matcher = BlockMatchers::OptionalBlock.new @ordering_constraints = [] @side_effects = [] @cardinality = Cardinality.new.exactly(1) @return_values = ReturnValues.new @yield_parameters = YieldParameters.new @backtrace = backtrace || caller end
def inspect
- Private: -
def inspect address = __id__ * 2 address += 0x100000000 if address < 0 "#<Expectation:0x#{format('%<address>x', address: address)} #{mocha_inspect} >" end
def invocations_allowed?
- Private: -
def invocations_allowed? @cardinality.invocations_allowed? end
def invoke(invocation)
- Private: -
def invoke(invocation) perform_side_effects @cardinality << invocation invocation.call(@yield_parameters, @return_values) end
def match?(invocation, ignoring_order: false)
- Private: -
def match?(invocation, ignoring_order: false) order_independent_match = @method_matcher.match?(invocation.method_name) && @parameters_matcher.match?(invocation.arguments) && @block_matcher.match?(invocation.block) ignoring_order ? order_independent_match : order_independent_match && in_correct_order? end
def matches_method?(method_name)
- Private: -
def matches_method?(method_name) @method_matcher.match?(method_name) end
def method_signature
- Private: -
def method_signature signature = "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}" signature << " #{@block_matcher.mocha_inspect}" if @block_matcher.mocha_inspect signature end
def mocha_inspect
- Private: -
def mocha_inspect message = "#{@cardinality.anticipated_times}, #{@cardinality.invoked_times}: #{method_signature}" message << "; #{@ordering_constraints.map(&:mocha_inspect).join('; ')}" unless @ordering_constraints.empty? if Mocha.configuration.display_matching_invocations_on_failure? message << @cardinality.actual_invocations end message end
def multiple_yields(*parameter_groups)
- Example: Yield different groups of parameters on different invocations of the expected method. Simulating a situation where the CSV file at 'path/to/file.csv' has been modified between the two calls to +foreach+. -
Example: When +foreach+ is called, the stub will invoke the block twice, the first time it passes ['row1_col1', 'row1_col2'] as the parameters, and the second time it passes ['row2_col1', ''] as the parameters. -
Other tags:
- See: #then -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
parameter_groups(*Array) -- each element of +parameter_groups+ should iself be an +Array+ representing the parameters to be passed to the block for a single yield. Any element of +parameter_groups+ that is not an +Array+ is wrapped in an +Array+.
def multiple_yields(*parameter_groups) @yield_parameters.add(*parameter_groups) self end
def never
- Example: Expected method must never be called. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def never @cardinality.exactly(0) self end
def once
- Example: Expected method must be invoked exactly once. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def once @cardinality.exactly(1) self end
def ordering_constraints_not_allowing_invocation_now
- Private: -
def ordering_constraints_not_allowing_invocation_now @ordering_constraints.reject(&:allows_invocation_now?) end
def perform_side_effects
- Private: -
def perform_side_effects @side_effects.each(&:perform) end
def raises(exception = RuntimeError, message = nil)
- Example: Raise an exception on first invocation of expected method and then return values on subsequent invocations. -
Example: Raise different exceptions on consecutive invocations of the expected method. -
Example: Raise custom exception with extra constructor parameters by passing in an instance of the exception. -
Example: Raise specified exception if expected method is invoked. -
Overloads:
-
def raises(exception, message) -
def raises(exception) -
def raises
Other tags:
- See: #then -
See: Kernel#raise -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
message(String) -- exception message. -
exception(Class, Exception, String, #exception) -- exception to be raised or message to be passed to RuntimeError.
def raises(exception = RuntimeError, message = nil) @return_values += ReturnValues.new(ExceptionRaiser.new(exception, message)) self end
def returns(*values)
- Example: Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an +Array+ of those values. -
Example: May be called in conjunction with {#raises} on the same expectation. -
Example: Alternative way to return a different value on consecutive invocations. -
Example: Return a different value on consecutive invocations. -
Example: Return the same value on every invocation. -
Parameters:
-
values(*Array) -- values to return on consecutive invocations of expected method. -
value(Object) -- value to return on invocation of expected method.
Overloads:
-
def returns(*values) -
def returns(value)
Other tags:
- See: #then -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def returns(*values) @return_values += ReturnValues.build(*values) self end
def satisfied?
- Private: -
def satisfied? @cardinality.satisfied? end
def then(state = nil)
- Example: Using {#then} to change the +state+ of a +state_machine+ on the invocation of an expected method. -
Example: Using {#then} as syntactic sugar when specifying values to be returned and exceptions to be raised on consecutive invocations of the expected method. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Other tags:
- See: #when -
See: StateMachine -
See: API#states -
Parameters:
-
state(StateMachine::State) -- state_machine.is(state_name) provides a mechanism to change the +state_machine+ into the state specified by +state_name+ when the expected method is invoked.
Overloads:
-
def then(state) -
def then
def then(state = nil) add_side_effect(ChangeStateSideEffect.new(state)) if state self end
def throws(tag, object = nil)
- Example: Throw tag on first invocation of expected method and then return values for subsequent invocations. -
Example: Throw different tags on consecutive invocations of the expected method. -
Example: Throw tag with return value +object+ c.f. +Kernel#throw+. -
Example: Throw tag when expected method is invoked. -
Overloads:
-
def throw(tag, object) -
def throw(tag)
Other tags:
- See: #then -
See: Kernel#throw -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
object(Object) -- return value for the catch block. -
tag(Symbol, String) -- tag to throw to transfer control to the active catch block.
def throws(tag, object = nil) @return_values += ReturnValues.new(Thrower.new(tag, object)) self end
def times(range)
- Example: Specifying a range in the number of expected invocations. -
Example: Specifying a specific number of expected invocations. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
range(Range, Integer) -- specifies the allowable range in the number of expected invocations.
def times(range) @cardinality.times(range) self end
def twice
- Example: Expected method must be invoked exactly twice. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def twice @cardinality.exactly(2) self end
def used?
- Private: -
def used? @cardinality.used? end
def verified?(assertion_counter = nil)
- Private: -
def verified?(assertion_counter = nil) assertion_counter.increment if assertion_counter && @cardinality.needs_verifying? @cardinality.verified? end
def when(state_predicate)
- Example: Using {#when} to only allow invocation of methods when "power" state machine is in the "on" state. -
Other tags:
- See: #then -
See: StateMachine -
See: API#states -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
state_predicate(StateMachine::StatePredicate) -- +state_machine.is(state_name)+ provides a mechanism to determine whether the +state_machine+ is in the state specified by +state_predicate+ when the expected method is invoked.
def when(state_predicate) add_ordering_constraint(InStateOrderingConstraint.new(state_predicate)) self end
def with(*expected_parameters_or_matchers, &matching_block)
- Example: Expected method must be called with a value divisible by 4. -
Example: Strict keyword argument matching -
Example: Loose keyword argument matching (default) -
Example: Expected method must be called with parameters matching parameter matchers. -
Example: Expected method must be called with exact parameter values. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Other tags:
- Yieldreturn: - +true+ if +actual_parameters+ are acceptable.
Other tags:
- Yieldparam: actual_parameters - parameters with which expected method was invoked.
Other tags:
- Yield: - optional block specifying custom matching.
Parameters:
-
expected_parameters_or_matchers(*Array) -- expected parameter values or parameter matchers.
Other tags:
- See: Configuration#strict_keyword_argument_matching= -
See: ParameterMatchers -
def with(*expected_parameters_or_matchers, &matching_block) @parameters_matcher = ParametersMatcher.new(expected_parameters_or_matchers, self, &matching_block) self end
def with_block_given
- Example: Expected method must be called with a block. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def with_block_given @block_matcher = BlockMatchers::BlockGiven.new self end
def with_no_block_given
- Example: Expected method must be called without a block. -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
def with_no_block_given @block_matcher = BlockMatchers::NoBlockGiven.new self end
def yields(*parameters)
- Example: Yield different parameters on different invocations of the expected method. -
Example: Yield parameters when expected method is invoked. -
Example: Yield when expected method is invoked. -
Other tags:
- See: #then -
Returns:
-
(Expectation)- the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
Parameters:
-
parameters(*Array) -- parameters to be yielded.
def yields(*parameters) multiple_yields(parameters) end