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 argument_list_matcher

Parameters:

  • value

    the value to set the attribute argument_list_matcher 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:

  • (@eval_context = Object.new.extend(RSpec::Mocks::InstanceExec))


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(&block)

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, &block)

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, &block)

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, &block)

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(&block)

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(&block)

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(&block)

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(&block)

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, &block)

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