Class: Mocha::Expectation

Class | Mocha::Expectation
In: | lib/mocha/expectation.rb
Parent: | Object

Methods on expectations returned from Mock#expects, Mock#stubs, Object#expects and Object#stubs.

### Methods

at_least at_least_once at_most at_most_once in_sequence multiple_yields never once raises returns then times twice when with yields

### Public Instance methods

at_least(minimum_number_of_times) → expectation

Modifies expectation so that the expected method must be called at least a `minimum_number_of_times`.

      object = mock()
      object.expects(:expected_method).at_least(2)
      3.times { object.expected_method }
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).at_least(2)
      object.expected_method
      # => verify fails

at_least_once() → expectation

Modifies expectation so that the expected method must be called at least once.

      object = mock()
      object.expects(:expected_method).at_least_once
      object.expected_method
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).at_least_once
      # => verify fails

at_most(maximum_number_of_times) → expectation

Modifies expectation so that the expected method must be called at most a `maximum_number_of_times`.

      object = mock()
      object.expects(:expected_method).at_most(2)
      2.times { object.expected_method }
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).at_most(2)
      3.times { object.expected_method }
      # => verify fails

at_most_once() → expectation

Modifies expectation so that the expected method must be called at most once.

      object = mock()
      object.expects(:expected_method).at_most_once
      object.expected_method
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).at_most_once
      2.times { object.expected_method }
      # => verify fails

in_sequence(*sequences) → expectation

Constrains this expectation so that it must be invoked at the current point in the sequence.

To expect a sequence of invocations, write the expectations in order and add the in_sequence(sequence) clause to each one.

Expectations in a sequence can have any invocation count.

If an expectation in a sequence is stubbed, rather than expected, it can be skipped in the sequence.

See also API#sequence.

      breakfast = sequence('breakfast')

      egg = mock('egg')
      egg.expects(:crack).in_sequence(breakfast)
      egg.expects(:fry).in_sequence(breakfast)
      egg.expects(:eat).in_sequence(breakfast)

multiple_yields(*parameter_groups) → expectation

Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified `parameter_groups`.

      object = mock()
      object.expects(:expected_method).multiple_yields(['result_1', 'result_2'], ['result_3'])
      yielded_values = []
      object.expected_method { |*values| yielded_values << values }
      yielded_values # => [['result_1', 'result_2'], ['result_3]]

May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.

      object = mock()
      object.stubs(:expected_method).multiple_yields([1, 2], [3]).then.multiple_yields([4], [5, 6])
      yielded_values_from_first_invocation = []
      yielded_values_from_second_invocation = []
      object.expected_method { |*values| yielded_values_from_first_invocation << values } # first invocation
      object.expected_method { |*values| yielded_values_from_second_invocation << values } # second invocation
      yielded_values_from_first_invocation # => [[1, 2], [3]]
      yielded_values_from_second_invocation # => [[4], [5, 6]]

never() → expectation

Modifies expectation so that the expected method must never be called.

      object = mock()
      object.expects(:expected_method).never
      object.expected_method
      # => verify fails

      object = mock()
      object.expects(:expected_method).never
      object.expected_method
      # => verify succeeds

once() → expectation

Modifies expectation so that the expected method must be called exactly once. Note that this is the default behaviour for an expectation, but you may wish to use it for clarity/emphasis.

      object = mock()
      object.expects(:expected_method).once
      object.expected_method
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).once
      object.expected_method
      object.expected_method
      # => verify fails

      object = mock()
      object.expects(:expected_method).once
      # => verify fails

raises(exception = RuntimeError, message = nil) → expectation

Modifies expectation so that when the expected method is called, it raises the specified `exception` with the specified `message`.

      object = mock()
      object.expects(:expected_method).raises(Exception, 'message')
      object.expected_method # => raises exception of class Exception and with message 'message'

May be called multiple times on the same expectation. Also see Expectation#then.

      object = mock()
      object.stubs(:expected_method).raises(Exception1).then.raises(Exception2)
      object.expected_method # => raises exception of class Exception1
      object.expected_method # => raises exception of class Exception2

May be called in conjunction with Expectation#returns on the same expectation.

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

returns(value) → expectation
returns(*values) → expectation

Modifies expectation so that when the expected method is called, it returns the specified `value`.

      object = mock()
      object.stubs(:stubbed_method).returns('result')
      object.stubbed_method # => 'result'
      object.stubbed_method # => 'result'

If multiple `values` are given, these are returned in turn on consecutive calls to the method.

      object = mock()
      object.stubs(:stubbed_method).returns(1, 2)
      object.stubbed_method # => 1
      object.stubbed_method # => 2

May be called multiple times on the same expectation. Also see Expectation#then.

      object = mock()
      object.stubs(:expected_method).returns(1, 2).then.returns(3)
      object.expected_method # => 1
      object.expected_method # => 2
      object.expected_method # => 3

May be called in conjunction with Expectation#raises on the same expectation.

      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

Note that in Ruby a method returning multiple values is exactly equivalent to a method returning an Array of those values.

      object = mock()
      object.stubs(:expected_method).returns([1, 2])
      x, y = object.expected_method
      x # => 1
      y # => 2

then() → expectation
then(state_machine.is(state)) → expectation

`then()` is used as syntactic sugar to improve readability. It has no effect on state of the expectation.

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

`then(state_machine.is(state))` is used to change the `state_machine` to the specified `state` when the invocation occurs.

See also API#states, StateMachine and Expectation#when.

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

times(range) → expectation

Modifies expectation so that the number of calls to the expected method must be within a specific `range`.

`range` can be specified as an exact integer or as a range of integers

      object = mock()
      object.expects(:expected_method).times(3)
      3.times { object.expected_method }
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).times(3)
      2.times { object.expected_method }
      # => verify fails

      object = mock()
      object.expects(:expected_method).times(2..4)
      3.times { object.expected_method }
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).times(2..4)
      object.expected_method
      # => verify fails

twice() → expectation

Modifies expectation so that the expected method must be called exactly twice.

      object = mock()
      object.expects(:expected_method).twice
      object.expected_method
      object.expected_method
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).twice
      object.expected_method
      object.expected_method
      object.expected_method
      # => verify fails

      object = mock()
      object.expects(:expected_method).twice
      object.expected_method
      # => verify fails

when(state_machine.is(state)) → exception

Constrains the expectation to occur only when the `state_machine` is in the named `state`.

See also API#states, StateMachine#starts_as and Expectation#then.

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

with(*expected_parameters, &matching_block) → expectation

Modifies expectation so that the expected method must be called with `expected_parameters`.

      object = mock()
      object.expects(:expected_method).with(:param1, :param2)
      object.expected_method(:param1, :param2)
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).with(:param1, :param2)
      object.expected_method(:param3)
      # => verify fails

May be used with parameter matchers in Mocha::ParameterMatchers.

If a `matching_block` is given, the block is called with the parameters passed to the expected method. The expectation is matched if the block evaluates to `true`.

      object = mock()
      object.expects(:expected_method).with() { |value| value % 4 == 0 }
      object.expected_method(16)
      # => verify succeeds

      object = mock()
      object.expects(:expected_method).with() { |value| value % 4 == 0 }
      object.expected_method(17)
      # => verify fails

yields(*parameters) → expectation

Modifies expectation so that when the expected method is called, it yields with the specified `parameters`.

      object = mock()
      object.expects(:expected_method).yields('result')
      yielded_value = nil
      object.expected_method { |value| yielded_value = value }
      yielded_value # => 'result'

May be called multiple times on the same expectation for consecutive invocations. Also see Expectation#then.

      object = mock()
      object.stubs(:expected_method).yields(1).then.yields(2)
      yielded_values_from_first_invocation = []
      yielded_values_from_second_invocation = []
      object.expected_method { |value| yielded_values_from_first_invocation << value } # first invocation
      object.expected_method { |value| yielded_values_from_second_invocation << value } # second invocation
      yielded_values_from_first_invocation # => [1]
      yielded_values_from_second_invocation # => [2]

[Validate]