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   when   with   yields  

Public Instance methods

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

[Source]

     # File lib/mocha/expectation.rb, line 98
 98:     def at_least(minimum_number_of_times)
 99:       @cardinality = Cardinality.at_least(minimum_number_of_times)
100:       self
101:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 114
114:     def at_least_once
115:       at_least(1)
116:       self
117:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 131
131:     def at_most(maximum_number_of_times)
132:       @cardinality = Cardinality.at_most(maximum_number_of_times)
133:       self
134:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 148
148:     def at_most_once()
149:       at_most(1)
150:       self
151:     end

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 Standalone#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)

[Source]

     # File lib/mocha/expectation.rb, line 346
346:     def in_sequence(*sequences)
347:       sequences.each { |sequence| add_in_sequence_ordering_constraint(sequence) }
348:       self
349:     end

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]]

[Source]

     # File lib/mocha/expectation.rb, line 222
222:     def multiple_yields(*parameter_groups)
223:       @yield_parameters.multiple_add(*parameter_groups)
224:       self
225:     end

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

[Source]

    # File lib/mocha/expectation.rb, line 81
81:     def never
82:       @cardinality = Cardinality.exactly(0)
83:       self
84:     end

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

[Source]

    # File lib/mocha/expectation.rb, line 64
64:     def once
65:       @cardinality = Cardinality.exactly(1)
66:       self
67:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 274
274:     def raises(exception = RuntimeError, message = nil)
275:       @return_values += ReturnValues.new(ExceptionRaiser.new(exception, message))
276:       self
277:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 252
252:     def returns(*values)
253:       @return_values += ReturnValues.build(*values)
254:       self
255:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 302
302:     def then(*parameters)
303:       if parameters.length == 1
304:         state = parameters.first
305:         add_side_effect(ChangeStateSideEffect.new(state))
306:       end
307:       self
308:     end

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

[Source]

    # File lib/mocha/expectation.rb, line 41
41:     def times(range)
42:       @cardinality = Cardinality.times(range)
43:       self
44:     end

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

See also Standalone#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'))

[Source]

     # File lib/mocha/expectation.rb, line 324
324:     def when(state_predicate)
325:       add_ordering_constraint(InStateOrderingConstraint.new(state_predicate))
326:       self
327:     end

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

[Source]

     # File lib/mocha/expectation.rb, line 178
178:     def with(*expected_parameters, &matching_block)
179:       @parameters_matcher = ParametersMatcher.new(expected_parameters, &matching_block)
180:       self
181:     end

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]

[Source]

     # File lib/mocha/expectation.rb, line 200
200:     def yields(*parameters)
201:       @yield_parameters.add(*parameters)
202:       self
203:     end

[Validate]