Class: FlexMock::Expectation

An Expectation is returned from each should_receive message sent to mock object. Each expectation records how a message matching the message name (argument to should_receive) and the argument list (given by with) should behave. Mock expectations can be recorded by chaining the declaration methods defined in this class.

For example:

  mock.should_receive(:meth).with(args).and_returns(result)

Methods

Attributes

[R]	expected_args
[RW]	mock
[R]	order_number

Public Class methods

new(mock, sym)

Create an expectation for a method named sym.

[ show source ]

    # File lib/flexmock/expectation.rb, line 34
34:     def initialize(mock, sym)
35:       @mock = mock
36:       @sym = sym
37:       @expected_args = nil
38:       @count_validators = []
39:       @count_validator_class = ExactCountValidator
40:       @actual_count = 0
41:       @return_value = nil
42:       @return_queue = []
43:       @yield_queue = []
44:       @order_number = nil
45:       @global_order_number = nil
46:       @globally = nil
47:     end

Public Instance methods

and_raise(an_exception)
and_raise(SomeException)
and_raise(SomeException, args, ...)

Declares that the method will raise the given exception (with an optional message) when executed.

If an exception instance is given, then that instance will be raised.
If an exception class is given, the exception raised with be an instance of that class constructed with new. Any additional arguments in the argument list will be passed to the new constructor when it is invoked.

raises is an alias for and_raise.

This method is also aliased as raises

[ show source ]

     # File lib/flexmock/expectation.rb, line 252
252:     def and_raise(exception, *args)
253:       and_return { raise exception, *args }
254:     end

and_return(value)
and_return(value, value, ...)
and_return { |*args| code }

Declare that the method returns a particular value (when the argument list is matched).

If a single value is given, it will be returned for all matching calls.
If multiple values are given, each value will be returned in turn for each successive call. If the number of matching calls is greater than the number of values, the last value will be returned for the extra matching calls.
If a block is given, it is evaluated on each call and its value is returned.

For example:

 mock.should_receive(:f).returns(12)   # returns 12

 mock.should_receive(:f).with(String). # returns an
   returns { |str| str.upcase }        # upcased string

returns is an alias for and_return.

This method is also aliased as returns

[ show source ]

     # File lib/flexmock/expectation.rb, line 188
188:     def and_return(*args, &block)
189:       if block_given? 
190:         @return_queue << block
191:       else
192:         args.each do |arg|
193:           @return_queue << lambda { |*a| arg }
194:         end
195:       end
196:       self
197:     end

and_return_undefined()

Declare that the method returns and undefined object (FlexMock.undefined). Since the undefined object will always return itself for any message sent to it, it is a good "I don‘t care" value to return for methods that are commonly used in method chains.

For example, if m.foo returns the undefined object, then:

   m.foo.bar.baz

returns the undefined object without throwing an exception.

This method is also aliased as returns_undefined

[ show source ]

     # File lib/flexmock/expectation.rb, line 212
212:     def and_return_undefined
213:       and_return(FlexMock.undefined)
214:     end

and_throw(a_symbol)
and_throw(a_symbol, value)

Declares that the method will throw the given symbol (with an optional value) when executed.

throws is an alias for and_throw.

This method is also aliased as throws

[ show source ]

     # File lib/flexmock/expectation.rb, line 266
266:     def and_throw(sym, value=nil)
267:       and_return { throw sym, value }
268:     end

and_yield(value1, value2, ...)

Declare that the mocked method is expected to be given a block and that the block will be called with the values supplied to yield. If the mock is called multiple times, mulitple and_yield declarations can be used to supply different values on each call.

An error is raised if the mocked method is not called with a block.

This method is also aliased as yields

[ show source ]

     # File lib/flexmock/expectation.rb, line 228
228:     def and_yield(*yield_values)
229:       @yield_queue << yield_values
230:     end

at_least()

Modifies the next call count declarator (times, never, once or twice) so that the declarator means the method is called at least that many times.

E.g. method f must be called at least twice:

  mock.should_receive(:f).at_least.twice

[ show source ]

     # File lib/flexmock/expectation.rb, line 314
314:     def at_least
315:       @count_validator_class = AtLeastCountValidator
316:       self
317:     end

at_most()

Modifies the next call count declarator (times, never, once or twice) so that the declarator means the method is called at most that many times.

E.g. method f must be called no more than twice

  mock.should_receive(:f).at_most.twice

[ show source ]

     # File lib/flexmock/expectation.rb, line 327
327:     def at_most
328:       @count_validator_class = AtMostCountValidator
329:       self
330:     end

by_default()

[ show source ]

     # File lib/flexmock/expectation.rb, line 388
388:     def by_default
389:       expectations = mock.flexmock_expectations_for(@sym)
390:       expectations.defaultify_expectation(self) if expectations
391:     end

call_count_constrained?()

Is this expectation constrained by any call counts?

[ show source ]

     # File lib/flexmock/expectation.rb, line 104
104:     def call_count_constrained?
105:       ! @count_validators.empty?
106:     end

eligible?()

Is this expectation eligible to be called again? It is eligible only if all of its count validators agree that it is eligible.

[ show source ]

     # File lib/flexmock/expectation.rb, line 99
 99:     def eligible?
100:       @count_validators.all? { |v| v.eligible?(@actual_count) }
101:     end

flexmock_verify()

Validate the correct number of calls have been made. Called by the teardown process.

[ show source ]

     # File lib/flexmock/expectation.rb, line 121
121:     def flexmock_verify
122:       @count_validators.each do |v|
123:         v.validate(@actual_count)
124:       end
125:     end

globally()

Modifier that changes the next ordered constraint to apply globally across all mock objects in the container.

[ show source ]

     # File lib/flexmock/expectation.rb, line 368
368:     def globally
369:       @globally = true
370:       self
371:     end

match_arg(expected, actual)

Does the expected argument match the corresponding actual value.

[ show source ]

     # File lib/flexmock/expectation.rb, line 138
138:     def match_arg(expected, actual)
139:       expected === actual ||
140:       expected == actual ||
141:       ( Regexp === expected && expected === actual.to_s )
142:     end

match_args(args)

Does the argument list match this expectation‘s argument specification.

[ show source ]

     # File lib/flexmock/expectation.rb, line 129
129:     def match_args(args)
130:       # TODO: Rethink this:
131:       # return false if @expected_args.nil?
132:       return true if @expected_args.nil?
133:       return false if args.size != @expected_args.size
134:       (0...args.size).all? { |i| match_arg(@expected_args[i], args[i]) }
135:     end

never()

Declare that the method is never expected to be called with the given argument list. This may be modified by the at_least and at_most declarators.

[ show source ]

     # File lib/flexmock/expectation.rb, line 288
288:     def never
289:       times(0)
290:     end

once()

Declare that the method is expected to be called exactly once with the given argument list. This may be modified by the at_least and at_most declarators.

[ show source ]

     # File lib/flexmock/expectation.rb, line 295
295:     def once
296:       times(1)
297:     end

ordered(group_name=nil)

Declare that the given method must be called in order. All ordered method calls must be received in the order specified by the ordering of the should_receive messages. Receiving a methods out of the specified order will cause a test failure.

If the user needs more fine control over ordering (e.g. specifying that a group of messages may be received in any order as long as they all come after another group of messages), a group name may be specified in the ordered calls. All messages within the same group may be received in any order.

For example, in the following, messages flip and flop may be received in any order (because they are in the same group), but must occur strictly after start but before end. The message any_time may be received at any time because it is not ordered.

   m = FlexMock.new
   m.should_receive(:any_time)
   m.should_receive(:start).ordered
   m.should_receive(:flip).ordered(:flip_flop_group)
   m.should_receive(:flop).ordered(:flip_flop_group)
   m.should_receive(:end).ordered

[ show source ]

     # File lib/flexmock/expectation.rb, line 356
356:     def ordered(group_name=nil)
357:       if @globally
358:         @global_order_number = define_ordered(group_name, @mock.flexmock_container)
359:       else
360:         @order_number = define_ordered(group_name, @mock)
361:       end
362:       @globally = false
363:       self
364:     end

raises(exception, *args)

Alias for and_raise

returns(*args, &block)

Alias for and_return

returns_undefined()

Alias for and_return_undefined

throws(sym, value=nil)

Alias for and_throw

times(limit)

Declare that the method is called limit times with the declared argument list. This may be modified by the at_least and at_most declarators.

[ show source ]

     # File lib/flexmock/expectation.rb, line 279
279:     def times(limit)
280:       @count_validators << @count_validator_class.new(self, limit) unless limit.nil?
281:       @count_validator_class = ExactCountValidator
282:       self
283:     end

to_s()

[ show source ]

    # File lib/flexmock/expectation.rb, line 49
49:     def to_s
50:       FlexMock.format_args(@sym, @expected_args)
51:     end

twice()

Declare that the method is expected to be called exactly twice with the given argument list. This may be modified by the at_least and at_most declarators.

[ show source ]

     # File lib/flexmock/expectation.rb, line 302
302:     def twice
303:       times(2)
304:     end

verify_call(*args)

Verify the current call with the given arguments matches the expectations recorded in this object.

[ show source ]

    # File lib/flexmock/expectation.rb, line 55
55:     def verify_call(*args)
56:       validate_order
57:       @actual_count += 1
58:       perform_yielding(args)
59:       return_value(args)
60:     end

with(*args)

Declare that the method should expect the given argument list.

[ show source ]

     # File lib/flexmock/expectation.rb, line 145
145:     def with(*args)
146:       @expected_args = args
147:       self
148:     end

with_any_args()

Declare that the method can be called with any number of arguments of any type.

[ show source ]

     # File lib/flexmock/expectation.rb, line 157
157:     def with_any_args
158:       @expected_args = nil
159:       self
160:     end

with_no_args()

Declare that the method should be called with no arguments.

[ show source ]

     # File lib/flexmock/expectation.rb, line 151
151:     def with_no_args
152:       with
153:     end

yields(*yield_values)

Alias for and_yield

zero_or_more_times()

Declare that the method may be called any number of times.

[ show source ]

     # File lib/flexmock/expectation.rb, line 272
272:     def zero_or_more_times
273:       at_least.never
274:     end