Methods on expectations returned from {Mock#expects}, {Mock#stubs}, {ObjectMethods#expects} and {ObjectMethods#stubs}.
@private
# File lib/mocha/expectation.rb, line 503 503: def initialize(mock, expected_method_name, backtrace = nil) 504: @mock = mock 505: @method_matcher = MethodMatcher.new(expected_method_name.to_sym) 506: @parameters_matcher = ParametersMatcher.new 507: @ordering_constraints = [] 508: @side_effects = [] 509: @cardinality, @invocation_count = Cardinality.exactly(1), 0 510: @return_values = ReturnValues.new 511: @yield_parameters = YieldParameters.new 512: @backtrace = backtrace || caller 513: end
@private
# File lib/mocha/expectation.rb, line 521 521: def add_in_sequence_ordering_constraint(sequence) 522: sequence.constrain_as_next_in_sequence(self) 523: end
@private
# File lib/mocha/expectation.rb, line 516 516: def add_ordering_constraint(ordering_constraint) 517: @ordering_constraints << ordering_constraint 518: end
@private
# File lib/mocha/expectation.rb, line 526 526: def add_side_effect(side_effect) 527: @side_effects << side_effect 528: end
Modifies expectation so that the expected method must be called at least a minimum_number_of_times.
@param [Integer] minimum_number_of_times minimum number of expected invocations. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 132 132: def at_least(minimum_number_of_times) 133: @cardinality = Cardinality.at_least(minimum_number_of_times) 134: self 135: end
Modifies expectation so that the expected method must be called at least once.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 150 150: def at_least_once 151: at_least(1) 152: self 153: end
Modifies expectation so that the expected method must be called at most a maximum_number_of_times.
@param [Integer] maximum_number_of_times maximum number of expected invocations. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 169 169: def at_most(maximum_number_of_times) 170: @cardinality = Cardinality.at_most(maximum_number_of_times) 171: self 172: end
Modifies expectation so that the expected method must be called at most once.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 187 187: def at_most_once() 188: at_most(1) 189: self 190: end
@private
# File lib/mocha/expectation.rb, line 536 536: def in_correct_order? 537: @ordering_constraints.all? { |ordering_constraint| ordering_constraint.allows_invocation_now? } 538: end
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.
@param [*Array
@see API#sequence
@example 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)
# File lib/mocha/expectation.rb, line 494 494: def in_sequence(*sequences) 495: sequences.each { |sequence| add_in_sequence_ordering_constraint(sequence) } 496: self 497: end
@private
# File lib/mocha/expectation.rb, line 551 551: def invocations_allowed? 552: @cardinality.invocations_allowed?(@invocation_count) 553: end
@private
# File lib/mocha/expectation.rb, line 561 561: def invoke 562: @invocation_count += 1 563: perform_side_effects() 564: if block_given? then 565: @yield_parameters.next_invocation.each do |yield_parameters| 566: yield(*yield_parameters) 567: end 568: end 569: @return_values.next 570: end
@private
# File lib/mocha/expectation.rb, line 546 546: def match?(actual_method_name, *actual_parameters) 547: @method_matcher.match?(actual_method_name) && @parameters_matcher.match?(actual_parameters) && in_correct_order? 548: end
@private
# File lib/mocha/expectation.rb, line 541 541: def matches_method?(method_name) 542: @method_matcher.match?(method_name) 543: end
@private
# File lib/mocha/expectation.rb, line 599 599: def method_signature 600: "#{@mock.mocha_inspect}.#{@method_matcher.mocha_inspect}#{@parameters_matcher.mocha_inspect}" 601: end
@private
# File lib/mocha/expectation.rb, line 584 584: def mocha_inspect 585: message = "#{@cardinality.mocha_inspect}, " 586: message << case @invocation_count 587: when 0 then "not yet invoked" 588: when 1 then "invoked once" 589: when 2 then "invoked twice" 590: else "invoked #{@invocation_count} times" 591: end 592: message << ": " 593: message << method_signature 594: message << "; #{@ordering_constraints.map { |oc| oc.mocha_inspect }.join("; ")}" unless @ordering_constraints.empty? 595: message 596: end
Modifies expectation so that when the expected method is called, it yields multiple times per invocation with the specified parameter_groups.
@param [*Array
@example 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]]
@example 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]]
# File lib/mocha/expectation.rb, line 279 279: def multiple_yields(*parameter_groups) 280: @yield_parameters.multiple_add(*parameter_groups) 281: self 282: end
Modifies expectation so that the expected method must never be called.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 112 112: def never 113: @cardinality = Cardinality.exactly(0) 114: self 115: 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.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 95 95: def once 96: @cardinality = Cardinality.exactly(1) 97: self 98: end
@private
# File lib/mocha/expectation.rb, line 531 531: def perform_side_effects 532: @side_effects.each { |side_effect| side_effect.perform } 533: end
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)+.
@param [Class,Exception,String,#] exception exception to be raised or message to be passed to RuntimeError. @param [String] message exception message. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@see Kernel#raise @see #
@overload def raises @overload def raises(exception) @overload def raises(exception, message)
@example 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'
@example 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
@example 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
@example 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
# File lib/mocha/expectation.rb, line 366 366: def raises(exception = RuntimeError, message = nil) 367: @return_values += ReturnValues.new(ExceptionRaiser.new(exception, message)) 368: self 369: end
Modifies expectation so that when the expected method is called, it returns the specified value.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained. @see #
@overload def returns(value)
@param [Object] value value to return on invocation of expected method.
@overload def returns(*values)
@param [*Array] values values to return on consecutive invocations of expected method.
@example Return the same value on every invocation.
object = mock() object.stubs(:stubbed_method).returns('result') object.stubbed_method # => 'result' object.stubbed_method # => 'result'
@example Return a different value on consecutive invocations.
object = mock() object.stubs(:stubbed_method).returns(1, 2) object.stubbed_method # => 1 object.stubbed_method # => 2
@example 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
@example May be called in conjunction with {#} 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
@example 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
# File lib/mocha/expectation.rb, line 326 326: def returns(*values) 327: @return_values += ReturnValues.build(*values) 328: self 329: end
@private
# File lib/mocha/expectation.rb, line 556 556: def satisfied? 557: @cardinality.satisfied?(@invocation_count) 558: end
@overload def then
Used as syntactic sugar to improve readability. It has no effect on state of the expectation.
@overload def then(state_machine.is(state_name))
Used to change the +state_machine+ to the state specified by +state_name+ when the expected invocation occurs. @param [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. @see API#states @see StateMachine @see #when
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example Using {#} 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
@example Using {#} 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'))
# File lib/mocha/expectation.rb, line 440 440: def then(*parameters) 441: if parameters.length == 1 442: state = parameters.first 443: add_side_effect(ChangeStateSideEffect.new(state)) 444: end 445: self 446: end
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)+.
@param [Symbol,String] tag tag to throw to transfer control to the active catch block. @param [Object] object return value for the catch block. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@see Kernel#throw @see #
@overload def throw(tag) @overload def throw(tag, object)
@example Throw tag when expected method is invoked.
object = stub() object.stubs(:expected_method).throws(:done) object.expected_method # => throws tag :done
@example 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'
@example 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
@example 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
# File lib/mocha/expectation.rb, line 405 405: def throws(tag, object = nil) 406: @return_values += ReturnValues.new(Thrower.new(tag, object)) 407: self 408: end
Modifies expectation so that the number of calls to the expected method must be within a specific range.
@param [Range,Integer] range specifies the allowable range in the number of expected invocations. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
@example 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
# File lib/mocha/expectation.rb, line 44 44: def times(range) 45: @cardinality = Cardinality.times(range) 46: self 47: end
Modifies expectation so that the expected method must be called exactly twice.
@return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
# File lib/mocha/expectation.rb, line 70 70: def twice 71: @cardinality = Cardinality.exactly(2) 72: self 73: end
@private
# File lib/mocha/expectation.rb, line 579 579: def used? 580: @cardinality.used?(@invocation_count) 581: end
@private
# File lib/mocha/expectation.rb, line 573 573: def verified?(assertion_counter = nil) 574: assertion_counter.increment if assertion_counter && @cardinality.needs_verifying? 575: @cardinality.verified?(@invocation_count) 576: end
Constrains the expectation to occur only when the state_machine is in the state specified by state_name.
@param [StateMachine::StatePredicate] state_machine.is(state_name) provides a mechanism to determine whether the state_machine is in the state specified by state_name when the expected method is invoked. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@see API#states @see StateMachine @see #
@example Using {#} 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'))
# File lib/mocha/expectation.rb, line 467 467: def when(state_predicate) 468: add_ordering_constraint(InStateOrderingConstraint.new(state_predicate)) 469: self 470: end
Modifies expectation so that the expected method must be called with expected_parameters.
May be used with parameter matchers in {ParameterMatchers}.
@param [*Array] expected_parameters parameters expected. @yield optional block specifying custom matching. @yieldparam [*Array] actual_parameters parameters with which expected method was invoked. @yieldreturn [Boolean] true if actual_parameters are acceptable. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained.
@example 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
@example 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
# File lib/mocha/expectation.rb, line 223 223: def with(*expected_parameters, &matching_block) 224: @parameters_matcher = ParametersMatcher.new(expected_parameters, &matching_block) 225: self 226: end
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.
@param [*Array] parameters parameters to be yielded. @return [Expectation] the same expectation, thereby allowing invocations of other {Expectation} methods to be chained. @see #
@example 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'
@example 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]
# File lib/mocha/expectation.rb, line 252 252: def yields(*parameters) 253: @yield_parameters.add(*parameters) 254: self 255: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.