class RSpec::Mocks::MessageExpectation

Attributes

argument_list_matcher[W]

error_generator[RW]

@private

expected_from[W]

expected_received_count[W]

message[R]

Public Class Methods

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

@private

# File lib/rspec/mocks/message_expectation.rb, line 12
def initialize(error_generator, expectation_ordering, expected_from, method_double,
               expected_received_count=1, opts={}, &implementation)
  @error_generator = error_generator
  @error_generator.opts = opts
  @expected_from = expected_from
  @method_double = method_double
  @message = @method_double.method_name
  @actual_received_count = 0
  @expected_received_count = expected_received_count
  @argument_list_matcher = ArgumentListMatcher.new(ArgumentMatchers::AnyArgsMatcher.new)
  @consecutive = false
  @exception_to_raise = nil
  @args_to_throw = []
  @order_group = expectation_ordering
  @at_least = @at_most = @exactly = nil
  @args_to_yield = []
  @failed_fast = nil
  @args_to_yield_were_cloned = false
  @eval_context = nil
  @implementation = implementation
end

Public Instance Methods

actual_received_count_matters?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 422
def actual_received_count_matters?
  @at_least || @at_most || @exactly
end

advise(*args) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 267
def advise(*args)
  similar_messages << args
end

and_call_original() click to toggle source

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

@note This is only available on partial mock objects.

@example

counter.should_receive(:increment).and_call_original
original_count = counter.count
counter.increment
expect(counter.count).to eq(original_count + 1)

# File lib/rspec/mocks/message_expectation.rb, line 113
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
    self.implementation = @method_double.original_method
  end
end

and_raise(exception = RuntimeError, message = nil) click to toggle source

@overload #and_raise @overload #and_raise(ExceptionClass) @overload #and_raise(ExceptionClass, message) @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 %xexception` and passing %xmessage`
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.

@example

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))

# File lib/rspec/mocks/message_expectation.rb, line 142
def and_raise(exception = RuntimeError, message = nil)
  if exception.respond_to?(:exception)
    @exception_to_raise = message ? exception.exception(message) : exception.exception
  else
    @exception_to_raise = exception
  end
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 96
def and_return(*values, &implementation)
  @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 and @at_least)
  @consecutive = true if values.size > 1
  @implementation = implementation || build_implementation(values)
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 160
def and_throw(symbol, object = nil)
  @args_to_throw = [symbol, object].compact
end

and_yield(*args) { |eval_context = object.extend(InstanceExec)| ... } 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 170
def and_yield(*args, &block)
  if @args_to_yield_were_cloned
    @args_to_yield.clear
    @args_to_yield_were_cloned = false
  end

  yield @eval_context = Object.new.extend(RSpec::Mocks::InstanceExec) if block

  @args_to_yield << args
  self
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 364
def any_number_of_times(&block)
  @implementation = block if block
  @expected_received_count = :any
  self
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_receive(:deal_card).at_least(9).times

# File lib/rspec/mocks/message_expectation.rb, line 332
def at_least(n, &block)
  @implementation = block if block
  set_expected_received_count :at_least, n
  self
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_receive(:deal_card).at_most(10).times

# File lib/rspec/mocks/message_expectation.rb, line 344
def at_most(n, &block)
  @implementation = block if block
  set_expected_received_count :at_most, n
  self
end

build_child(expected_from, expected_received_count, opts={}, &implementation) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 41
def build_child(expected_from, expected_received_count, opts={}, &implementation)
  child = clone
  child.expected_from = expected_from
  child.implementation = implementation if implementation
  child.expected_received_count = expected_received_count
  child.clear_actual_received_count!
  new_gen = error_generator.clone
  new_gen.opts = opts
  child.error_generator = new_gen
  child.clone_args_to_yield(*@args_to_yield)
  child.argument_list_matcher = ArgumentListMatcher.new(ArgumentMatchers::AnyArgsMatcher.new)
  child
end

called_max_times?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 216
def called_max_times?
  @expected_received_count != :any &&
    !@at_least &&
    @expected_received_count > 0 &&
    @actual_received_count >= @expected_received_count
end

exactly(n, &block) click to toggle source

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

@example

dealer.should_receive(:deal_card).exactly(10).times

# File lib/rspec/mocks/message_expectation.rb, line 320
def exactly(n, &block)
  @implementation = block if block
  set_expected_received_count :exactly, n
  self
end

expected_args() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 56
def expected_args
  @argument_list_matcher.expected_args
end

expected_messages_received?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 237
def expected_messages_received?
  ignoring_args? || matches_exact_count? || matches_at_least_count? || matches_at_most_count?
end

generate_error() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 272
def generate_error
  if similar_messages.empty?
    @error_generator.raise_expectation_error(@message, @expected_received_count, @actual_received_count, *expected_args)
  else
    @error_generator.raise_similar_message_args_error(self, *@similar_messages)
  end
end

ignoring_args?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 242
def ignoring_args?
  @expected_received_count == :any
end

increase_actual_received_count!() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 427
def increase_actual_received_count!
  @actual_received_count += 1
end

invoke(*args, &block) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 188
def invoke(*args, &block)
  if (@expected_received_count == 0 && !@at_least) || ((@exactly || @at_most) && (@actual_received_count == @expected_received_count))
    @actual_received_count += 1
    @failed_fast = true
    @error_generator.raise_expectation_error(@message, @expected_received_count, @actual_received_count, *args)
  end

  @order_group.handle_order_constraint self

  begin
    raise(@exception_to_raise) unless @exception_to_raise.nil?
    Kernel::throw(*@args_to_throw) unless @args_to_throw.empty?

    default_return_val = call_with_yield(&block) if !@args_to_yield.empty? || @eval_context

    if @consecutive
      call_implementation_consecutive(*args, &block)
    elsif @implementation
      call_implementation(*args, &block)
    else
      default_return_val
    end
  ensure
    @actual_received_count += 1
  end
end

matches?(message, *args) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 183
def matches?(message, *args)
  @message == message && @argument_list_matcher.args_match?(*args)
end

matches_at_least_count?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 247
def matches_at_least_count?
  @at_least && @actual_received_count >= @expected_received_count
end

matches_at_most_count?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 252
def matches_at_most_count?
  @at_most && @actual_received_count <= @expected_received_count
end

matches_exact_count?() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 257
def matches_exact_count?
  @expected_received_count == @actual_received_count
end

matches_name_but_not_args(message, *args) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 224
def matches_name_but_not_args(message, *args)
  @message == message and not @argument_list_matcher.args_match?(*args)
end

negative_expectation_for?(message) click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 417
def negative_expectation_for?(message)
  return false
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 375
def never
  @expected_received_count = 0
  self
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 385
def once(&block)
  @implementation = block if block
  set_expected_received_count :exactly, 1
  self
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 409
def ordered(&block)
  @implementation = block if block
  @order_group.register(self)
  @ordered = true
  self
end

raise_out_of_order_error() click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 280
def raise_out_of_order_error
  @error_generator.raise_out_of_order_error @message
end

similar_messages() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 262
def similar_messages
  @similar_messages ||= []
end

times(&block) click to toggle source

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

@example

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

# File lib/rspec/mocks/message_expectation.rb, line 357
def times(&block)
  @implementation = block if block
  self
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 396
def twice(&block)
  @implementation = block if block
  set_expected_received_count :exactly, 2
  self
end

verify_messages_received() click to toggle source

@private

# File lib/rspec/mocks/message_expectation.rb, line 229
def verify_messages_received
  generate_error unless expected_messages_received? || failed_fast?
rescue RSpec::Mocks::MockExpectationError => error
  error.backtrace.insert(0, @expected_from)
  Kernel::raise error
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 308
def with(*args, &block)
  @implementation = block if block_given? unless args.empty?
  @argument_list_matcher = ArgumentListMatcher.new(*args, &block)
  self
end

Protected Instance Methods

call_implementation(*args, &block) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 450
def call_implementation(*args, &block)
  @implementation.arity == 0 ? @implementation.call(&block) : @implementation.call(*args, &block)
end

call_implementation_consecutive(*args, &block) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 445
def call_implementation_consecutive(*args, &block)
  @value ||= call_implementation(*args, &block)
  @value[[@actual_received_count, @value.size-1].min]
end

call_with_yield(&block) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 433
def call_with_yield(&block)
  @error_generator.raise_missing_block_error @args_to_yield unless block
  value = nil
  @args_to_yield.each do |args|
    if block.arity > -1 && args.length != block.arity
      @error_generator.raise_wrong_arity_error args, block.arity
    end
    value = @eval_context ? @eval_context.instance_exec(*args, &block) : block.call(*args)
  end
  value
end

clear_actual_received_count!() click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 474
def clear_actual_received_count!
  @actual_received_count = 0
end

clone_args_to_yield(*args) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 454
def clone_args_to_yield(*args)
  @args_to_yield = args.clone
  @args_to_yield_were_cloned = true
end

failed_fast?() click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 459
def failed_fast?
  @failed_fast
end

implementation=(implementation) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 34
def implementation=(implementation)
  @consecutive = false
  @implementation = implementation
end

set_expected_received_count(relativity, n) click to toggle source

# File lib/rspec/mocks/message_expectation.rb, line 463
def set_expected_received_count(relativity, n)
  @at_least = (relativity == :at_least)
  @at_most  = (relativity == :at_most)
  @exactly  = (relativity == :exactly)
  @expected_received_count = case n
                             when Numeric then n
                             when :once   then 1
                             when :twice  then 2
                             end
end