class Mocha::Expectation

Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.

def add_in_sequence_ordering_constraint(sequence)

Other tags:
    Private: -
def add_in_sequence_ordering_constraint(sequence)
  sequence.constrain_as_next_in_sequence(self)
end

def add_ordering_constraint(ordering_constraint)

Other tags:
    Private: -
def add_ordering_constraint(ordering_constraint)
  @ordering_constraints << ordering_constraint
end

def add_side_effect(side_effect)

Other tags:
    Private: -
def add_side_effect(side_effect)
  @side_effects << side_effect
end

def at_least(minimum_number_of_times)

Other tags:
    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

Other tags:
    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)

Other tags:
    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

Other tags:
    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

Other tags:
    Private: -
def definition_location
  filter = BacktraceFilter.new
  filter.filtered(backtrace)[0]
end

def in_correct_order?

Other tags:
    Private: -
def in_correct_order?
  @ordering_constraints.all?(&:allows_invocation_now?)
end

def in_sequence(sequence, *sequences)

Other tags:
    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)

Other tags:
    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

Other tags:
    Private: -
def inspect
  address = __id__ * 2
  address += 0x100000000 if address < 0
  "#<Expectation:0x#{format('%<address>x', address: address)} #{mocha_inspect} >"
end

def invocations_allowed?

Other tags:
    Private: -
def invocations_allowed?
  @cardinality.invocations_allowed?
end

def invoke(invocation)

Other tags:
    Private: -
def invoke(invocation)
  perform_side_effects
  @cardinality << invocation
  invocation.call(@yield_parameters, @return_values)
end

def match?(invocation, ignoring_order: false)

Other tags:
    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)

Other tags:
    Private: -
def matches_method?(method_name)
  @method_matcher.match?(method_name)
end

def method_signature

Other tags:
    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

Other tags:
    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)

Other tags:
    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

Other tags:
    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

Other tags:
    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

Other tags:
    Private: -
def ordering_constraints_not_allowing_invocation_now
  @ordering_constraints.reject(&:allows_invocation_now?)
end

def perform_side_effects

Other tags:
    Private: -
def perform_side_effects
  @side_effects.each(&:perform)
end

def raises(exception = RuntimeError, message = nil)

Other tags:
    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)

Other tags:
    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?

Other tags:
    Private: -
def satisfied?
  @cardinality.satisfied?
end

def then(state = nil)

Other tags:
    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)

Other tags:
    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)

Other tags:
    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

Other tags:
    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?

Other tags:
    Private: -
def used?
  @cardinality.used?
end

def verified?(assertion_counter = nil)

Other tags:
    Private: -
def verified?(assertion_counter = nil)
  assertion_counter.increment if assertion_counter && @cardinality.needs_verifying?
  @cardinality.verified?
end

def when(state_predicate)

Other tags:
    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)

Other tags:
    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

Other tags:
    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

Other tags:
    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)

Other tags:
    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