Parent

RSpec::Mocks::MessageExpectation

Attributes

message[R]

@private

expected_received_count[W]
expected_from[W]
argument_expectation[W]
implementation[W]
error_generator[RW]

Public Class Methods

new(error_generator, expectation_ordering, expected_from, message, expected_received_count=1, opts={}, &implementation) click to toggle source

@private

    # File lib/rspec/mocks/message_expectation.rb, line 13
13:       def initialize(error_generator, expectation_ordering, expected_from, message, expected_received_count=1, opts={}, &implementation)
14:         @error_generator = error_generator
15:         @error_generator.opts = opts
16:         @expected_from = expected_from
17:         @message = message
18:         @actual_received_count = 0
19:         @expected_received_count = expected_received_count
20:         @argument_expectation = ArgumentExpectation.new(ArgumentMatchers::AnyArgsMatcher.new)
21:         @consecutive = false
22:         @exception_to_raise = nil
23:         @args_to_throw = []
24:         @order_group = expectation_ordering
25:         @at_least = @at_most = @exactly = nil
26:         @args_to_yield = []
27:         @failed_fast = nil
28:         @args_to_yield_were_cloned = false
29:         @eval_context = nil
30:         @implementation = implementation
31:       end

Public Instance Methods

actual_received_count_matters?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 399
399:       def actual_received_count_matters?
400:         @at_least || @at_most || @exactly
401:       end
advise(*args) click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 244
244:       def advise(*args)
245:         similar_messages << args
246:       end
and_raise(exception=Exception) click to toggle source

@overload and_raise @overload and_raise(ExceptionClass) @overload and_raise(exception_instance)

Tells the object to raise an exception when the message is received.

@note

  When you pass an exception class, the MessageExpectation will raise
  an instance of it, creating it with `new`. If the exception class
  initializer requires any parameters, you must pass in an instance and
  not the class.

@example

  car.stub(:go).and_raise
  car.stub(:go).and_raise(OutOfGas)
  car.stub(:go).and_raise(OutOfGas.new(2, :oz))
     # File lib/rspec/mocks/message_expectation.rb, line 113
113:       def and_raise(exception=Exception)
114:         @exception_to_raise = exception
115:       end
and_return(*values, &implementation) click to toggle source

@overload and_return(value) @overload and_return(first_value, second_value) @overload and_return(&block)

Tells the object to return a value when it receives the message. Given more than one value, the first value is returned the first time the message is received, the second value is returned the next time, etc, etc.

If the message is received more times than there are values, the last value is received for every subsequent call.

The block format is still supported, but is unofficially deprecated in favor of just passing a block to the stub method.

@example

  counter.stub(:count).and_return(1)
  counter.count # => 1
  counter.count # => 1

  counter.stub(:count).and_return(1,2,3)
  counter.count # => 1
  counter.count # => 2
  counter.count # => 3
  counter.count # => 3
  counter.count # => 3
  # etc

  # Supported, but ...
  counter.stub(:count).and_return { 1 }
  counter.count # => 1

  # ... this is prefered
  counter.stub(:count) { 1 }
  counter.count # => 1
    # File lib/rspec/mocks/message_expectation.rb, line 89
89:       def and_return(*values, &implementation)
90:         @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 and @at_least)
91:         @consecutive = true if values.size > 1
92:         @implementation = implementation || build_implementation(values)
93:       end
and_throw(symbol, object = nil) click to toggle source

@overload and_throw(symbol) @overload and_throw(symbol, object)

Tells the object to throw a symbol (with the object if that form is used) when the message is received.

@example

  car.stub(:go).and_throw(:out_of_gas)
  car.stub(:go).and_throw(:out_of_gas, :level => 0.1)
     # File lib/rspec/mocks/message_expectation.rb, line 127
127:       def and_throw(symbol, object = nil)
128:         @args_to_throw = [symbol, object].compact
129:       end
and_yield(*args, &block) click to toggle source

Tells the object to yield one or more args to a block when the message is received.

@example

  stream.stub(:open).and_yield(StringIO.new)
     # File lib/rspec/mocks/message_expectation.rb, line 137
137:       def and_yield(*args, &block)
138:         if @args_to_yield_were_cloned
139:           @args_to_yield.clear
140:           @args_to_yield_were_cloned = false
141:         end
142: 
143:         yield @eval_context = Object.new.extend(RSpec::Mocks::InstanceExec) if block
144: 
145:         @args_to_yield << args
146:         self
147:       end
any_number_of_times(&block) click to toggle source

Allows an expected message to be received any number of times.

     # File lib/rspec/mocks/message_expectation.rb, line 341
341:       def any_number_of_times(&block)
342:         @implementation = block if block
343:         @expected_received_count = :any
344:         self
345:       end
at_least(n, &block) click to toggle source

Constrain a message expectation to be received at least a specific number of times.

@example

  dealer.should_recieve(:deal_card).at_least(9).times
     # File lib/rspec/mocks/message_expectation.rb, line 309
309:       def at_least(n, &block)
310:         @implementation = block if block
311:         set_expected_received_count :at_least, n
312:         self
313:       end
at_most(n, &block) click to toggle source

Constrain a message expectation to be received at most a specific number of times.

@example

  dealer.should_recieve(:deal_card).at_most(10).times
     # File lib/rspec/mocks/message_expectation.rb, line 321
321:       def at_most(n, &block)
322:         @implementation = block if block
323:         set_expected_received_count :at_most, n
324:         self
325:       end
build_child(expected_from, expected_received_count, opts={}, &implementation) click to toggle source

@private

    # File lib/rspec/mocks/message_expectation.rb, line 34
34:       def build_child(expected_from, expected_received_count, opts={}, &implementation)
35:         child = clone
36:         child.expected_from = expected_from
37:         child.implementation = implementation if implementation
38:         child.expected_received_count = expected_received_count
39:         child.clear_actual_received_count!
40:         new_gen = error_generator.clone
41:         new_gen.opts = opts
42:         child.error_generator = new_gen
43:         child.clone_args_to_yield(*@args_to_yield)
44:         child.argument_expectation = ArgumentExpectation.new(ArgumentMatchers::AnyArgsMatcher.new)
45:         child
46:       end
called_max_times?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 196
196:       def called_max_times?
197:         @expected_received_count != :any && @expected_received_count > 0 && @actual_received_count >= @expected_received_count
198:       end
exactly(n, &block) click to toggle source

Constrain a message expectation to be received a specific number of times.

@example

  dealer.should_recieve(:deal_card).exactly(10).times
     # File lib/rspec/mocks/message_expectation.rb, line 297
297:       def exactly(n, &block)
298:         @implementation = block if block
299:         set_expected_received_count :exactly, n
300:         self
301:       end
expected_args() click to toggle source

@private

    # File lib/rspec/mocks/message_expectation.rb, line 49
49:       def expected_args
50:         @argument_expectation.args
51:       end
expected_messages_received?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 214
214:       def expected_messages_received?
215:         ignoring_args? || matches_exact_count? || matches_at_least_count? || matches_at_most_count?
216:       end
generate_error() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 249
249:       def generate_error
250:         if similar_messages.empty?
251:           @error_generator.raise_expectation_error(@message, @expected_received_count, @actual_received_count, *@argument_expectation.args)
252:         else
253:           @error_generator.raise_similar_message_args_error(self, *@similar_messages)
254:         end
255:       end
ignoring_args?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 219
219:       def ignoring_args?
220:         @expected_received_count == :any
221:       end
increase_actual_received_count!() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 404
404:       def increase_actual_received_count!
405:         @actual_received_count += 1
406:       end
invoke(*args, &block) click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 155
155:       def invoke(*args, &block)
156:         if (@expected_received_count == 0 && !@at_least) || ((@exactly || @at_most) && (@actual_received_count == @expected_received_count))
157:           @actual_received_count += 1
158:           @failed_fast = true
159:           @error_generator.raise_expectation_error(@message, @expected_received_count, @actual_received_count, *args)
160:         end
161: 
162:         @order_group.handle_order_constraint self
163: 
164:         begin
165:           raise_exception unless @exception_to_raise.nil?
166:           Kernel::throw(*@args_to_throw) unless @args_to_throw.empty?
167: 
168:           default_return_val = call_with_yield(&block) if !@args_to_yield.empty? || @eval_context
169: 
170:           if @consecutive
171:             call_implementation_consecutive(*args, &block)
172:           elsif @implementation
173:             call_implementation(*args, &block)
174:           else
175:             default_return_val
176:           end
177:         ensure
178:           @actual_received_count += 1
179:         end
180:       end
matches?(message, *args) click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 150
150:       def matches?(message, *args)
151:         @message == message && @argument_expectation.args_match?(*args)
152:       end
matches_at_least_count?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 224
224:       def matches_at_least_count?
225:         @at_least && @actual_received_count >= @expected_received_count
226:       end
matches_at_most_count?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 229
229:       def matches_at_most_count?
230:         @at_most && @actual_received_count <= @expected_received_count
231:       end
matches_exact_count?() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 234
234:       def matches_exact_count?
235:         @expected_received_count == @actual_received_count
236:       end
matches_name_but_not_args(message, *args) click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 201
201:       def matches_name_but_not_args(message, *args)
202:         @message == message and not @argument_expectation.args_match?(*args)
203:       end
negative_expectation_for?(message) click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 394
394:       def negative_expectation_for?(message)
395:         return false
396:       end
never() click to toggle source

Expect a message not to be received at all.

@example

  car.should_receive(:stop).never
     # File lib/rspec/mocks/message_expectation.rb, line 352
352:       def never
353:         @expected_received_count = 0
354:         self
355:       end
once(&block) click to toggle source

Expect a message to be received exactly one time.

@example

  car.should_receive(:go).once
     # File lib/rspec/mocks/message_expectation.rb, line 362
362:       def once(&block)
363:         @implementation = block if block
364:         set_expected_received_count :exactly, 1
365:         self
366:       end
ordered(&block) click to toggle source

Expect messages to be received in a specific order.

@example

  api.should_receive(:prepare).ordered
  api.should_receive(:run).ordered
  api.should_receive(:finish).ordered
     # File lib/rspec/mocks/message_expectation.rb, line 386
386:       def ordered(&block)
387:         @implementation = block if block
388:         @order_group.register(self)
389:         @ordered = true
390:         self
391:       end
raise_exception() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 183
183:       def raise_exception
184:         if !@exception_to_raise.respond_to?(:instance_method) ||
185:             @exception_to_raise.instance_method(:initialize).arity <= 0
186:           raise(@exception_to_raise)
187:         else
188:           raise ArgumentError.new('and_raise' can only accept an Exception class if an instance can be constructed with no arguments.#{@exception_to_raise.to_s}'s initialize method requires #{@exception_to_raise.instance_method(:initialize).arity} arguments, so you have to supply an instance instead.)
189:         end
190:       end
raise_out_of_order_error() click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 257
257:       def raise_out_of_order_error
258:         @error_generator.raise_out_of_order_error @message
259:       end
similar_messages() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 239
239:       def similar_messages
240:         @similar_messages ||= []
241:       end
times(&block) click to toggle source

Syntactic sugar for `exactly`, `at_least` and `at_most`

@example

  dealer.should_recieve(:deal_card).exactly(10).times
  dealer.should_recieve(:deal_card).at_least(10).times
  dealer.should_recieve(:deal_card).at_most(10).times
     # File lib/rspec/mocks/message_expectation.rb, line 334
334:       def times(&block)
335:         @implementation = block if block
336:         self
337:       end
twice(&block) click to toggle source

Expect a message to be received exactly two times.

@example

  car.should_receive(:go).twice
     # File lib/rspec/mocks/message_expectation.rb, line 373
373:       def twice(&block)
374:         @implementation = block if block
375:         set_expected_received_count :exactly, 2
376:         self
377:       end
verify_messages_received() click to toggle source

@private

     # File lib/rspec/mocks/message_expectation.rb, line 206
206:       def verify_messages_received
207:         generate_error unless expected_messages_received? || failed_fast?
208:       rescue RSpec::Mocks::MockExpectationError => error
209:         error.backtrace.insert(0, @expected_from)
210:         Kernel::raise error
211:       end
with(*args, &block) click to toggle source

Constrains a stub or message expectation to invocations with specific arguments.

With a stub, if the message might be received with other args as well, you should stub a default value first, and then stub or mock the same message using `with` to constrain to specific arguments.

A message expectation will fail if the message is received with different arguments.

@example

  cart.stub(:add) { :failure }
  cart.stub(:add).with(Book.new(:isbn => 1934356379)) { :success }
  cart.add(Book.new(:isbn => 1234567890))
  # => :failure
  cart.add(Book.new(:isbn => 1934356379))
  # => :success

  cart.should_receive(:add).with(Book.new(:isbn => 1934356379)) { :success }
  cart.add(Book.new(:isbn => 1234567890))
  # => failed expectation
  cart.add(Book.new(:isbn => 1934356379))
  # => passes
     # File lib/rspec/mocks/message_expectation.rb, line 285
285:       def with(*args, &block)
286:         @implementation = block if block_given? unless args.empty?
287:         @argument_expectation = ArgumentExpectation.new(*args, &block)
288:         self
289:       end

Protected Instance Methods

call_implementation(*args, &block) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 427
427:       def call_implementation(*args, &block)
428:         @implementation.arity == 0 ? @implementation.call(&block) : @implementation.call(*args, &block)
429:       end
call_implementation_consecutive(*args, &block) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 422
422:       def call_implementation_consecutive(*args, &block)
423:         @value ||= call_implementation(*args, &block)
424:         @value[[@actual_received_count, @value.size-1].min]
425:       end
call_with_yield(&block) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 410
410:       def call_with_yield(&block)
411:         @error_generator.raise_missing_block_error @args_to_yield unless block
412:         value = nil
413:         @args_to_yield.each do |args|
414:           if block.arity > 1 && args.length != block.arity
415:             @error_generator.raise_wrong_arity_error args, block.arity
416:           end
417:           value = @eval_context ? @eval_context.instance_exec(*args, &block) : block.call(*args)
418:         end
419:         value
420:       end
clear_actual_received_count!() click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 451
451:       def clear_actual_received_count!
452:         @actual_received_count = 0
453:       end
clone_args_to_yield(*args) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 431
431:       def clone_args_to_yield(*args)
432:         @args_to_yield = args.clone
433:         @args_to_yield_were_cloned = true
434:       end
failed_fast?() click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 436
436:       def failed_fast?
437:         @failed_fast
438:       end
set_expected_received_count(relativity, n) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 440
440:       def set_expected_received_count(relativity, n)
441:         @at_least = (relativity == :at_least)
442:         @at_most  = (relativity == :at_most)
443:         @exactly  = (relativity == :exactly)
444:         @expected_received_count = case n
445:                                    when Numeric then n
446:                                    when :once   then 1
447:                                    when :twice  then 2
448:                                    end
449:       end

Private Instance Methods

build_implementation(values) click to toggle source
     # File lib/rspec/mocks/message_expectation.rb, line 457
457:       def build_implementation(values)
458:         value = values.size == 1 ? values.first : values
459:         lambda { value }
460:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.