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.

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

- (Object) message (readonly)

Returns the value of attribute message

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

- (Object) orig_object (readonly)

Returns the value of attribute orig_object

9
10
11
 
# File 'lib/rspec/mocks/message_expectation.rb', line 9
def orig_object
  @orig_object
end

- (Object) warn_about_yielding_receiver_to_implementation_block

Returns the value of attribute warnaboutyieldingreceivertoimplementationblock

7
8
9
 
# File 'lib/rspec/mocks/message_expectation.rb', line 7
def warn_about_yielding_receiver_to_implementation_block
  @warn_about_yielding_receiver_to_implementation_block
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)
123
124
125
126
127
128
129
130
 
# File 'lib/rspec/mocks/message_expectation.rb', line 123
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)
    @yield_receiver_to_implementation_block = false
  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))
153
154
155
156
157
158
159
160
 
# File 'lib/rspec/mocks/message_expectation.rb', line 153
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 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

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

# ... use this instead
counter.stub(:count) { 1 }
counter.count # => 1
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/rspec/mocks/message_expectation.rb', line 79
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
    RSpec.deprecate('`and_return { value }`',
                    :replacement => '`and_return(value)` or an implementation block without `and_return`')
    self.inner_implementation_action = implementation
  else
    if values.empty?
      RSpec.warn_deprecation('`and_return` without arguments is deprecated. ' +
                             'Remove the `and_return`. ' +
                             "Called from #{CallerFilter.first_non_rspec_line}.")
    end
    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)
172
173
174
175
 
# File 'lib/rspec/mocks/message_expectation.rb', line 172
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:

183
184
185
186
187
188
 
# File 'lib/rspec/mocks/message_expectation.rb', line 183
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) and_yield_receiver_to_implementation 

103
104
105
106
 
# File 'lib/rspec/mocks/message_expectation.rb', line 103
def and_yield_receiver_to_implementation
  @yield_receiver_to_implementation_block = true
  self
end

- (Object) any_number_of_times

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

421
422
423
424
425
426
 
# File 'lib/rspec/mocks/message_expectation.rb', line 421
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
385
386
387
388
389
390
391
392
393
 
# File 'lib/rspec/mocks/message_expectation.rb', line 385
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
401
402
403
404
405
 
# File 'lib/rspec/mocks/message_expectation.rb', line 401
def at_most(n, &block)
  self.inner_implementation_action = block
  set_expected_received_count :at_most, n
  self
end

- (Object) display_any_instance_deprecation_warning(block_source_line) 

500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
 
# File 'lib/rspec/mocks/message_expectation.rb', line 500
def display_any_instance_deprecation_warning(block_source_line)
  RSpec.warn_deprecation(<<MSG
In RSpec 3, `any_instance` implementation blocks will be yielded the receiving
instance as the first block argument to allow the implementation block to use
the state of the receiver.  To maintain compatibility with RSpec 3 you need to
either set rspec-mocks' `yield_receiver_to_any_instance_implementation_blocks`
config option to `false` OR set it to `true` and update your `any_instance`
implementation blocks to account for the first block argument being the receiving instance.
To set the config option, use a snippet like:
RSpec.configure do |rspec|
  rspec.mock_with :rspec do |mocks|
    mocks.yield_receiver_to_any_instance_implementation_blocks = false
  end
end
Your `any_instance` implementation block is declared at: #{block_source_line}
MSG
)
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
373
374
375
376
377
 
# File 'lib/rspec/mocks/message_expectation.rb', line 373
def exactly(n, &block)
  self.inner_implementation_action = block
  set_expected_received_count :exactly, n
  self
end

- (Object) expectation_count_type 

314
315
316
317
318
 
# File 'lib/rspec/mocks/message_expectation.rb', line 314
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
433
434
435
436
437
 
# File 'lib/rspec/mocks/message_expectation.rb', line 433
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
444
445
446
447
448
 
# File 'lib/rspec/mocks/message_expectation.rb', line 444
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
468
469
470
471
472
473
 
# File 'lib/rspec/mocks/message_expectation.rb', line 468
def ordered(&block)
  self.inner_implementation_action = block
  @order_group.register(self)
  @ordered = true
  self
end

- (Object) raise_out_of_order_error 

325
326
327
 
# File 'lib/rspec/mocks/message_expectation.rb', line 325
def raise_out_of_order_error
  @error_generator.raise_out_of_order_error @message
end

- (Object) should_display_any_instance_deprecation_warning 

495
496
497
498
 
# File 'lib/rspec/mocks/message_expectation.rb', line 495
def should_display_any_instance_deprecation_warning
  warn_about_yielding_receiver_to_implementation_block &&
    !@have_warned_about_yielding_receiver
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
414
415
416
417
 
# File 'lib/rspec/mocks/message_expectation.rb', line 414
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
455
456
457
458
459
 
# File 'lib/rspec/mocks/message_expectation.rb', line 455
def twice(&block)
  self.inner_implementation_action = block
  set_expected_received_count :exactly, 2
  self
end

- (Object) warn_about_receiver_passing(any_instance_source_line) 

490
491
492
493
 
# File 'lib/rspec/mocks/message_expectation.rb', line 490
def warn_about_receiver_passing(any_instance_source_line)
  @any_instance_source_line = any_instance_source_line
  @warn_about_yielding_receiver_to_implementation_block = true
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
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/rspec/mocks/message_expectation.rb', line 353
def with(*args, &block)
  if block_given?
    if args.empty?
      RSpec.deprecate "Using the return value of a `with` block to validate passed arguments rather than as an implementation",
        :replacement => "the `satisfy` matcher, a custom matcher or validate the arguments in an implementation block"
    else
      self.inner_implementation_action = block
    end
  end
  @argument_list_matcher = ArgumentListMatcher.new(*args, &block)
  self
end

- (Boolean) yield_receiver_to_implementation_block?

Returns:

  • (Boolean) 
108
109
110
 
# File 'lib/rspec/mocks/message_expectation.rb', line 108
def yield_receiver_to_implementation_block?
  @yield_receiver_to_implementation_block
end