Class: Mocha::Expectation

Inherits:
Object show all
Defined in:
lib/mocha/expectation.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mock, expected_method_name, backtrace = nil) ⇒ Expectation

Returns a new instance of Expectation.


503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/mocha/expectation.rb', line 503

def initialize(mock, expected_method_name, backtrace = nil)
  @mock = mock
  @method_matcher = MethodMatcher.new(expected_method_name.to_sym)
  @parameters_matcher = ParametersMatcher.new
  @ordering_constraints = []
  @side_effects = []
  @cardinality, @invocation_count = Cardinality.exactly(1), 0
  @return_values = ReturnValues.new
  @yield_parameters = YieldParameters.new
  @backtrace = backtrace || caller
end

Instance Attribute Details

#backtrace ⇒ Object (readonly) 


500
501
502
 
# File 'lib/mocha/expectation.rb', line 500

def backtrace
  @backtrace
end

Instance Method Details

#add_in_sequence_ordering_constraint(sequence) ⇒ Object 


521
522
523
 
# File 'lib/mocha/expectation.rb', line 521

def add_in_sequence_ordering_constraint(sequence)
  sequence.constrain_as_next_in_sequence(self)
end

#add_ordering_constraint(ordering_constraint) ⇒ Object 


516
517
518
 
# File 'lib/mocha/expectation.rb', line 516

def add_ordering_constraint(ordering_constraint)
  @ordering_constraints << ordering_constraint
end

#add_side_effect(side_effect) ⇒ Object 


526
527
528
 
# File 'lib/mocha/expectation.rb', line 526

def add_side_effect(side_effect)
  @side_effects << side_effect
end

#at_least(minimum_number_of_times) ⇒ Expectation

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

Examples:

Expected method must be called at least twice.

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

Parameters:

  • minimum_number_of_times (Integer) —

    minimum number of expected invocations.

Returns:


132
133
134
135
 
# File 'lib/mocha/expectation.rb', line 132

def at_least(minimum_number_of_times)
  @cardinality = Cardinality.at_least(minimum_number_of_times)
  self
end

#at_least_once ⇒ Expectation

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

Examples:

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

Returns:


150
151
152
153
 
# File 'lib/mocha/expectation.rb', line 150

def at_least_once
  at_least(1)
  self
end

#at_most(maximum_number_of_times) ⇒ Expectation

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

Examples:

Expected method must be called at most twice.

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 } # => unexpected invocation

Parameters:

  • maximum_number_of_times (Integer) —

    maximum number of expected invocations.

Returns:


169
170
171
172
 
# File 'lib/mocha/expectation.rb', line 169

def at_most(maximum_number_of_times)
  @cardinality = Cardinality.at_most(maximum_number_of_times)
  self
end

#at_most_once ⇒ Expectation

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

Examples:

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 } # => unexpected invocation

Returns:


187
188
189
190
 
# File 'lib/mocha/expectation.rb', line 187

def at_most_once()
  at_most(1)
  self
end

#in_correct_order? ⇒ Boolean

Returns:

  • (Boolean) 

536
537
538
 
# File 'lib/mocha/expectation.rb', line 536

def in_correct_order?
  @ordering_constraints.all? { |ordering_constraint| ordering_constraint.allows_invocation_now? }
end

#in_sequence(*sequences) ⇒ Expectation

Constrains the 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.

An expected method can appear in multiple sequences.

Examples:

Ensure methods are invoked in a specified order.

breakfast = sequence('breakfast')

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

Parameters:

  • sequences (*Array<Sequence>) —

    sequences in which expected method should appear.

Returns:

See Also:


494
495
496
497
 
# File 'lib/mocha/expectation.rb', line 494

def in_sequence(*sequences)
  sequences.each { |sequence| add_in_sequence_ordering_constraint(sequence) }
  self
end

#invocations_allowed? ⇒ Boolean

Returns:

  • (Boolean) 

551
552
553
 
# File 'lib/mocha/expectation.rb', line 551

def invocations_allowed?
  @cardinality.invocations_allowed?(@invocation_count)
end

#invoke ⇒ Object 


561
562
563
564
565
566
567
568
569
570
 
# File 'lib/mocha/expectation.rb', line 561

def invoke
  @invocation_count += 1
  perform_side_effects()
  if block_given? then
    @yield_parameters.next_invocation.each do |yield_parameters|
      yield(*yield_parameters)
    end
  end
  @return_values.next
end

#match?(actual_method_name, *actual_parameters) ⇒ Boolean

Returns:

  • (Boolean) 

546
547
548
 
# File 'lib/mocha/expectation.rb', line 546

def match?(actual_method_name, *actual_parameters)
  @method_matcher.match?(actual_method_name) && @parameters_matcher.match?(actual_parameters) && in_correct_order?
end

#matches_method?(method_name) ⇒ Boolean

Returns:

  • (Boolean) 

541
542
543
 
# File 'lib/mocha/expectation.rb', line 541

def matches_method?(method_name)
  @method_matcher.match?(method_name)
end

#method_signature ⇒ Object 


599
600
601
 
# File 'lib/mocha/expectation.rb', line 599

def method_signature
  "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}"
end

#mocha_inspect ⇒ Object 


584
585
586
587
588
589
590
591
592
593
594
595
596
 
# File 'lib/mocha/expectation.rb', line 584

def mocha_inspect
  message = "#{@cardinality.mocha_inspect}, "
  message << case @invocation_count
    when 0 then "not yet invoked"
    when 1 then "invoked once"
    when 2 then "invoked twice"
    else "invoked #{@invocation_count} times"
  end
  message << ": "
  message << method_signature
  message << "; #{@ordering_constraints.map { |oc| oc.mocha_inspect }.join("; ")}" unless @ordering_constraints.empty?
  message
end

#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.

Examples:

When the expected_method is called, the stub will invoke the block twice, the first time it passes 'result_1', 'result_2' as the parameters, and the second time it passes 'result_3' as the parameters.

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

Yield different groups of parameters on different invocations of the expected method.

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

Parameters:

  • parameter_groups (*Array<Array>) —

    each element of parameter_groups should iself be an Array representing the parameters to be passed to the block for a single yield.

Returns:

See Also:


279
280
281
282
 
# File 'lib/mocha/expectation.rb', line 279

def multiple_yields(*parameter_groups)
  @yield_parameters.multiple_add(*parameter_groups)
  self
end

#never ⇒ Expectation

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

Examples:

Expected method must never be called.

object = mock()
object.expects(:expected_method).never
object.expected_method # => unexpected invocation

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

Returns:


112
113
114
115
 
# File 'lib/mocha/expectation.rb', line 112

def never
  @cardinality = Cardinality.exactly(0)
  self
end

#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.

Examples:

Expected method must be invoked exactly once.

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 # => unexpected invocation

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

Returns:


95
96
97
98
 
# File 'lib/mocha/expectation.rb', line 95

def once
  @cardinality = Cardinality.exactly(1)
  self
end

#perform_side_effects ⇒ Object 


531
532
533
 
# File 'lib/mocha/expectation.rb', line 531

def perform_side_effects
  @side_effects.each { |side_effect| side_effect.perform }
end

#raises ⇒ Expectation #raises(exception) ⇒ Expectation #raises(exception, message) ⇒ Expectation

Modifies expectation so that when the expected method is called, it raises the specified exception with the specified message i.e. calls Kernel#raise(exception, message).

Examples:

Raise specified exception if expected method is invoked.

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

Raise custom exception with extra constructor parameters by passing in an instance of the exception.

object = stub()
object.stubs(:expected_method).raises(MyException.new('message', 1, 2, 3))
object.expected_method # => raises the specified instance of MyException

Raise different exceptions on consecutive invocations of the expected method.

object = stub()
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

Raise an exception on first invocation of expected method and then return values on subsequent invocations.

object = stub()
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

Parameters:

  • exception (Class, Exception, String, #exception) (defaults to: RuntimeError) —

    exception to be raised or message to be passed to RuntimeError.

  • message (String) (defaults to: nil) —

    exception message.

Returns:

See Also:


366
367
368
369
 
# File 'lib/mocha/expectation.rb', line 366

def raises(exception = RuntimeError, message = nil)
  @return_values += ReturnValues.new(ExceptionRaiser.new(exception, message))
  self
end

#returns(value) ⇒ Expectation #returns(*values) ⇒ Expectation

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

Examples:

Return the same value on every invocation.

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

Return a different value on consecutive invocations.

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

Alternative way to return a different value on consecutive invocations.

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

Overloads:

  • #returns(value) ⇒ Expectation

    Parameters:

    • value (Object) —

      value to return on invocation of expected method.

  • #returns(*values) ⇒ Expectation

    Parameters:

    • values (*Array) —

      values to return on consecutive invocations of expected method.

Returns:

See Also:


326
327
328
329
 
# File 'lib/mocha/expectation.rb', line 326

def returns(*values)
  @return_values += ReturnValues.build(*values)
  self
end

#satisfied? ⇒ Boolean

Returns:

  • (Boolean) 

556
557
558
 
# File 'lib/mocha/expectation.rb', line 556

def satisfied?
  @cardinality.satisfied?(@invocation_count)
end

#then ⇒ Expectation #then(state_machine.is(state_name)) ⇒ Expectation

Returns the same expectation, thereby allowing invocations of other Mocha::Expectation methods to be chained.

Examples:

Using #then as syntactic sugar when specifying values to be returned and exceptions to be raised on consecutive invocations of the expected method.

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

Using #then to change the state of a state_machine on the invocation of an expected method.

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

Overloads:

  • #then ⇒ Expectation

    Used as syntactic sugar to improve readability. It has no effect on state of the expectation.

  • #then(state_machine.is(state_name)) ⇒ Expectation

    Used to change the state_machine to the state specified by state_name when the expected invocation occurs.

    Parameters:

    • state_machine.is(state_name) (StateMachine::State) —

      provides a mechanism to change the state_machine into the state specified by state_name when the expected method is invoked.

    See Also:

Returns:


440
441
442
443
444
445
446
 
# File 'lib/mocha/expectation.rb', line 440

def then(*parameters)
  if parameters.length == 1
    state = parameters.first
    add_side_effect(ChangeStateSideEffect.new(state))
  end
  self
end

#throw(tag) ⇒ Expectation #throw(tag, object) ⇒ Expectation

Modifies expectation so that when the expected method is called, it throws the specified tag with the specific return value object i.e. calls Kernel#throw(tag, object).

Examples:

Throw tag when expected method is invoked.

object = stub()
object.stubs(:expected_method).throws(:done)
object.expected_method # => throws tag :done

Throw tag with return value object c.f. Kernel#throw.

object = stub()
object.stubs(:expected_method).throws(:done, 'result')
object.expected_method # => throws tag :done and causes catch block to return 'result'

Throw different tags on consecutive invocations of the expected method.

object = stub()
object.stubs(:expected_method).throws(:done).then.throws(:continue)
object.expected_method # => throws :done
object.expected_method # => throws :continue

Throw tag on first invocation of expected method and then return values for subsequent invocations.

object = stub()
object.stubs(:expected_method).throws(:done).then.returns(2, 3)
object.expected_method # => throws :done
object.expected_method # => 2
object.expected_method # => 3

Parameters:

  • tag (Symbol, String) —

    tag to throw to transfer control to the active catch block.

  • object (Object) (defaults to: nil) —

    return value for the catch block.

Returns:

See Also:


405
406
407
408
 
# File 'lib/mocha/expectation.rb', line 405

def throws(tag, object = nil)
  @return_values += ReturnValues.new(Thrower.new(tag, object))
  self
end

#times(range) ⇒ Expectation

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

Examples:

Specifying a specific number of expected invocations.

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

Specifying a range in the number of expected invocations.

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

Parameters:

  • range (Range, Integer) —

    specifies the allowable range in the number of expected invocations.

Returns:


44
45
46
47
 
# File 'lib/mocha/expectation.rb', line 44

def times(range)
  @cardinality = Cardinality.times(range)
  self
end

#twice ⇒ Expectation

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

Examples:

Expected method must be invoked 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 # => unexpected invocation

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

Returns:


70
71
72
73
 
# File 'lib/mocha/expectation.rb', line 70

def twice
  @cardinality = Cardinality.exactly(2)
  self
end

#used? ⇒ Boolean

Returns:

  • (Boolean) 

579
580
581
 
# File 'lib/mocha/expectation.rb', line 579

def used?
  @cardinality.used?(@invocation_count)
end

#verified?(assertion_counter = nil) ⇒ Boolean

Returns:

  • (Boolean) 

573
574
575
576
 
# File 'lib/mocha/expectation.rb', line 573

def verified?(assertion_counter = nil)
  assertion_counter.increment if assertion_counter && @cardinality.needs_verifying?
  @cardinality.verified?(@invocation_count)
end

#when(state_predicate) ⇒ Expectation

Constrains the expectation to occur only when the state_machine is in the state specified by state_name.

Examples:

Using #when to only allow invocation of methods when “power” state machine is in the “on” state.

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

Parameters:

  • state_machine.is(state_name) (StateMachine::StatePredicate) —

    provides a mechanism to determine whether the state_machine is in the state specified by state_name when the expected method is invoked.

Returns:

See Also:


467
468
469
470
 
# File 'lib/mocha/expectation.rb', line 467

def when(state_predicate)
  add_ordering_constraint(InStateOrderingConstraint.new(state_predicate))
  self
end

#with(*expected_parameters) {|actual_parameters| ... } ⇒ Expectation

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

May be used with parameter matchers in ParameterMatchers.

Examples:

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

Expected method must be called with a value divisible by 4.

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

Parameters:

  • expected_parameters (*Array) —

    parameters expected.

Yields:

  • optional block specifying custom matching.

Yield Parameters:

  • actual_parameters (*Array) —

    parameters with which expected method was invoked.

Yield Returns:

  • (Boolean) —

    true if actual_parameters are acceptable.

Returns:


223
224
225
226
 
# File 'lib/mocha/expectation.rb', line 223

def with(*expected_parameters, &matching_block)
  @parameters_matcher = ParametersMatcher.new(expected_parameters, &matching_block)
  self
end

#yields(*parameters) ⇒ Expectation

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

May be called multiple times on the same expectation for consecutive invocations.

Examples:

Yield parameters when expected method is invoked.

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

Yield different parameters on different invocations of the expected method.

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]

Parameters:

  • parameters (*Array) —

    parameters to be yielded.

Returns:

See Also:


252
253
254
255
 
# File 'lib/mocha/expectation.rb', line 252

def yields(*parameters)
  @yield_parameters.add(*parameters)
  self
end