Class: RSpec::Mocks::MessageExpectation

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/mocks/message_expectation.rb

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Instance Attribute Details

- (Object) argument_list_matcher=(value) (writeonly)

Sets the attribute argumentlistmatcher

Parameters:

  • value —

    the value to set the attribute argumentlistmatcher to.

8
9
10
 
# File 'lib/rspec/mocks/message_expectation.rb', line 8
def argument_list_matcher=(value)
  @argument_list_matcher = value
end

- (Object) message (readonly)

Returns the value of attribute message

7
8
9
 
# File 'lib/rspec/mocks/message_expectation.rb', line 7
def message
  @message
end

Instance Method Details

- (Object) and_call_original

Note:

This is only available on partial mock objects.

Tells the object to delegate to the original unmodified method when it receives the message.

Examples:

counter.should_receive(:increment).and_call_original
original_count = counter.count
counter.increment
expect(counter.count).to eq(original_count + 1)
101
102
103
104
105
106
107
 
# File 'lib/rspec/mocks/message_expectation.rb', line 101
def and_call_original
  if @method_double.object.is_a?(RSpec::Mocks::TestDouble)
    @error_generator.raise_only_valid_on_a_partial_mock(:and_call_original)
  else
    @implementation = AndCallOriginalImplementation.new(@method_double.original_method)
  end
end

- (Object) and_raise - (Object) and_raise(ExceptionClass) - (Object) and_raise(ExceptionClass, message) - (Object) and_raise(exception_instance)

Note:

When you pass an exception class, the MessageExpectation will raise an instance of it, creating it with exception and passing message if specified. If the exception class initializer requires more than one parameters, you must pass in an instance and not the class, otherwise this method will raise an ArgumentError exception.

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

Examples:

car.stub(:go).and_raise
car.stub(:go).and_raise(OutOfGas)
car.stub(:go).and_raise(OutOfGas, "At least 2 oz of gas needed to drive")
car.stub(:go).and_raise(OutOfGas.new(2, :oz))
130
131
132
133
134
135
136
137
 
# File 'lib/rspec/mocks/message_expectation.rb', line 130
def and_raise(exception = RuntimeError, message = nil)
  if exception.respond_to?(:exception)
    exception = message ? exception.exception(message) : exception.exception
  end
  self.terminal_implementation_action = Proc.new { raise exception }
  nil
end

- (Object) and_return(value) - (Object) and_return(first_value, second_value) - (Object) 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.

Examples:

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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/rspec/mocks/message_expectation.rb', line 73
def and_return(*values, &implementation)
  if negative?
    RSpec.deprecate "`and_return` on a negative message expectation"
  end
  @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 and @at_least)
  if implementation
    # TODO: deprecate `and_return { value }`
    self.inner_implementation_action = implementation
  else
    self.terminal_implementation_action = AndReturnImplementation.new(values)
  end
  nil
end

- (Object) and_throw(symbol) - (Object) and_throw(symbol, object)

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

Examples:

car.stub(:go).and_throw(:out_of_gas)
car.stub(:go).and_throw(:out_of_gas, :level => 0.1)
149
150
151
152
 
# File 'lib/rspec/mocks/message_expectation.rb', line 149
def and_throw(*args)
  self.terminal_implementation_action = Proc.new { throw(*args) }
  nil
end

- (Object) and_yield(*args) {|@eval_context = Object.new.extend(RSpec::Mocks::InstanceExec)| ... }

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

Examples:

stream.stub(:open).and_yield(StringIO.new)

Yields:

160
161
162
163
164
165
 
# File 'lib/rspec/mocks/message_expectation.rb', line 160
def and_yield(*args, &block)
  yield @eval_context = Object.new.extend(RSpec::Mocks::InstanceExec) if block
  @args_to_yield << args
  self.initial_implementation_action = AndYieldImplementation.new(@args_to_yield, @eval_context, @error_generator)
  self
end

- (Object) any_number_of_times

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

364
365
366
367
368
369
 
# File 'lib/rspec/mocks/message_expectation.rb', line 364
def any_number_of_times(&block)
  RSpec.deprecate "any_number_of_times", :replacement => "stub"
  self.inner_implementation_action = block
  @expected_received_count = :any
  self
end

- (Object) at_least(n)

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

Examples:

dealer.should_receive(:deal_card).at_least(9).times
328
329
330
331
332
333
334
335
336
 
# File 'lib/rspec/mocks/message_expectation.rb', line 328
def at_least(n, &block)
  if n == 0
    RSpec.deprecate "at_least(0) with should_receive", :replacement => "stub"
  end
  self.inner_implementation_action = block
  set_expected_received_count :at_least, n
  self
end

- (Object) at_most(n)

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

Examples:

dealer.should_receive(:deal_card).at_most(10).times
344
345
346
347
348
 
# File 'lib/rspec/mocks/message_expectation.rb', line 344
def at_most(n, &block)
  self.inner_implementation_action = block
  set_expected_received_count :at_most, n
  self
end

- (Object) exactly(n)

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

Examples:

dealer.should_receive(:deal_card).exactly(10).times
316
317
318
319
320
 
# File 'lib/rspec/mocks/message_expectation.rb', line 316
def exactly(n, &block)
  self.inner_implementation_action = block
  set_expected_received_count :exactly, n
  self
end

- (Object) expectation_count_type 

265
266
267
268
269
 
# File 'lib/rspec/mocks/message_expectation.rb', line 265
def expectation_count_type
  return :at_least if @at_least
  return :at_most if @at_most
  return nil
end

- (Object) never

Expect a message not to be received at all.

Examples:

car.should_receive(:stop).never
376
377
378
379
380
 
# File 'lib/rspec/mocks/message_expectation.rb', line 376
def never
  ErrorGenerator.raise_double_negation_error("expect(obj)") if negative?
  @expected_received_count = 0
  self
end

- (Object) once

Expect a message to be received exactly one time.

Examples:

car.should_receive(:go).once
387
388
389
390
391
 
# File 'lib/rspec/mocks/message_expectation.rb', line 387
def once(&block)
  self.inner_implementation_action = block
  set_expected_received_count :exactly, 1
  self
end

- (Object) ordered

Expect messages to be received in a specific order.

Examples:

api.should_receive(:prepare).ordered
api.should_receive(:run).ordered
api.should_receive(:finish).ordered
411
412
413
414
415
416
 
# File 'lib/rspec/mocks/message_expectation.rb', line 411
def ordered(&block)
  self.inner_implementation_action = block
  @order_group.register(self)
  @ordered = true
  self
end

- (Object) raise_out_of_order_error 

276
277
278
 
# File 'lib/rspec/mocks/message_expectation.rb', line 276
def raise_out_of_order_error
  @error_generator.raise_out_of_order_error @message
end

- (Object) times

Syntactic sugar for exactly, at_least and at_most

Examples:

dealer.should_receive(:deal_card).exactly(10).times
dealer.should_receive(:deal_card).at_least(10).times
dealer.should_receive(:deal_card).at_most(10).times
357
358
359
360
 
# File 'lib/rspec/mocks/message_expectation.rb', line 357
def times(&block)
  self.inner_implementation_action = block
  self
end

- (Object) twice

Expect a message to be received exactly two times.

Examples:

car.should_receive(:go).twice
398
399
400
401
402
 
# File 'lib/rspec/mocks/message_expectation.rb', line 398
def twice(&block)
  self.inner_implementation_action = block
  set_expected_received_count :exactly, 2
  self
end

- (Object) with(*args)

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.

Examples:

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
304
305
306
307
308
 
# File 'lib/rspec/mocks/message_expectation.rb', line 304
def with(*args, &block)
  self.inner_implementation_action = block if block_given? unless args.empty?
  @argument_list_matcher = ArgumentListMatcher.new(*args, &block)
  self
end