Class: RSpec::Mocks::MessageExpectation

### Home Classes Methods

### In Files

- lib/rspec/mocks/message_expectation.rb

### Parent

Object

### Namespace

- MODULE RSpec::Mocks::MessageExpectation::ImplementationDetails

### Methods

- #and_call_original
- #and_raise
- #and_return
- #and_throw
- #and_wrap_original
- #and_yield
- #at_least
- #at_most
- #exactly
- #never
- #once
- #ordered
- #thrice
- #times
- #twice
- #with

### Included Modules

- RSpec::Mocks::MessageExpectation::ImplementationDetails

### Class/Module Index

Quicksearch

- RSpec
- RSpec::Mocks
- RSpec::Mocks::AllowanceTarget
- RSpec::Mocks::AndReturnImplementation
- RSpec::Mocks::AndWrapOriginalImplementation
- RSpec::Mocks::AndYieldImplementation
- RSpec::Mocks::AnyInstance
- RSpec::Mocks::AnyInstance::Chain
- RSpec::Mocks::AnyInstance::Chain::Customizations
- RSpec::Mocks::AnyInstance::ExpectChainChain
- RSpec::Mocks::AnyInstance::ExpectationChain
- RSpec::Mocks::AnyInstance::FluentInterfaceProxy
- RSpec::Mocks::AnyInstance::MessageChains
- RSpec::Mocks::AnyInstance::PositiveExpectationChain
- RSpec::Mocks::AnyInstance::Proxy
- RSpec::Mocks::AnyInstance::Recorder
- RSpec::Mocks::AnyInstance::StubChain
- RSpec::Mocks::AnyInstance::StubChainChain
- RSpec::Mocks::AnyInstanceAllowanceTarget
- RSpec::Mocks::AnyInstanceExpectationTarget
- RSpec::Mocks::ArgumentListMatcher
- RSpec::Mocks::ArgumentMatchers
- RSpec::Mocks::ArgumentMatchers::AnyArgMatcher
- RSpec::Mocks::ArgumentMatchers::AnyArgsMatcher
- RSpec::Mocks::ArgumentMatchers::ArrayIncludingMatcher
- RSpec::Mocks::ArgumentMatchers::BaseHashMatcher
- RSpec::Mocks::ArgumentMatchers::BooleanMatcher
- RSpec::Mocks::ArgumentMatchers::DuckTypeMatcher
- RSpec::Mocks::ArgumentMatchers::HashExcludingMatcher
- RSpec::Mocks::ArgumentMatchers::HashIncludingMatcher
- RSpec::Mocks::ArgumentMatchers::InstanceOf
- RSpec::Mocks::ArgumentMatchers::KindOf
- RSpec::Mocks::ArgumentMatchers::NoArgsMatcher
- RSpec::Mocks::ArgumentMatchers::SingletonMatcher
- RSpec::Mocks::ClassVerifyingDouble
- RSpec::Mocks::Configuration
- RSpec::Mocks::Constant
- RSpec::Mocks::ConstantMutator
- RSpec::Mocks::ConstantMutator::BaseMutator
- RSpec::Mocks::ConstantMutator::ConstantHider
- RSpec::Mocks::ConstantMutator::DefinedConstantReplacer
- RSpec::Mocks::ConstantMutator::UndefinedConstantSetter
- RSpec::Mocks::DirectObjectReference
- RSpec::Mocks::Double
- RSpec::Mocks::ErrorGenerator
- RSpec::Mocks::ExampleMethods
- RSpec::Mocks::ExampleMethods::ExpectHost
- RSpec::Mocks::ExpectChain
- RSpec::Mocks::ExpectationTarget
- RSpec::Mocks::Implementation
- RSpec::Mocks::InsertOntoBacktrace
- RSpec::Mocks::InstanceMethodReference
- RSpec::Mocks::InstanceMethodStasher
- RSpec::Mocks::InstanceVerifyingDouble
- RSpec::Mocks::MarshalExtension
- RSpec::Mocks::Matchers
- RSpec::Mocks::Matchers::ExpectationCustomization
- RSpec::Mocks::Matchers::HaveReceived
- RSpec::Mocks::Matchers::Receive
- RSpec::Mocks::Matchers::Receive::DefaultDescribable
- RSpec::Mocks::Matchers::ReceiveMessageChain
- RSpec::Mocks::Matchers::ReceiveMessages
- RSpec::Mocks::MessageChain
- RSpec::Mocks::MessageExpectation
- RSpec::Mocks::MessageExpectation::ImplementationDetails
- RSpec::Mocks::MethodDouble
- RSpec::Mocks::MethodReference
- RSpec::Mocks::NamedObjectReference
- RSpec::Mocks::NestedSpace
- RSpec::Mocks::ObjectMethodReference
- RSpec::Mocks::ObjectReference
- RSpec::Mocks::ObjectVerifyingDouble
- RSpec::Mocks::ObjectVerifyingDoubleMethods
- RSpec::Mocks::OrderGroup
- RSpec::Mocks::PartialClassDoubleProxy
- RSpec::Mocks::PartialClassDoubleProxyMethods
- RSpec::Mocks::PartialDoubleProxy
- RSpec::Mocks::Proxy
- RSpec::Mocks::ProxyForNil
- RSpec::Mocks::RootSpace
- RSpec::Mocks::SimpleMessageExpectation
- RSpec::Mocks::Space
- RSpec::Mocks::Space::FakeMutex
- RSpec::Mocks::StubChain
- RSpec::Mocks::Syntax
- RSpec::Mocks::TargetBase
- RSpec::Mocks::TestDouble
- RSpec::Mocks::TestDoubleProxy
- RSpec::Mocks::VerifyingDouble
- RSpec::Mocks::VerifyingExistingMethodDouble
- RSpec::Mocks::VerifyingMessageExpectation
- RSpec::Mocks::VerifyingMethodDouble
- RSpec::Mocks::VerifyingPartialClassDoubleProxy
- RSpec::Mocks::VerifyingPartialDoubleProxy
- RSpec::Mocks::VerifyingProxy
- RSpec::Mocks::VerifyingProxyMethods
- RSpec::Mocks::Version
- BasicObject
- Class

No matching classes.

# RSpec::Mocks::MessageExpectation

Represents an individual method stub or message expectation. The methods defined here can be used to configure how it behaves. The methods return `self` so that they can be chained together to form a fluent interface.

### Public Instance Methods

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 doubles.

@return [nil] No further chaining is supported after this. @example

    expect(counter).to 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 95
    def and_call_original
      and_wrap_original do |original, *args, &block|
        original.call(*args, &block)
      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.

@return [nil] No further chaining is supported after this. @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.

@example

    allow(car).to receive(:go).and_raise
    allow(car).to receive(:go).and_raise(OutOfGas)
    allow(car).to receive(:go).and_raise(OutOfGas, "At least 2 oz of gas needed to drive")
    allow(car).to receive(:go).and_raise(OutOfGas.new(2, :oz))

    # File lib/rspec/mocks/message_expectation.rb, line 145
    def and_raise(exception=RuntimeError, message=nil)
      raise_already_invoked_error_if_necessary(__method__)
      if exception.respond_to?(:exception)
        exception = message ? exception.exception(message) : exception.exception
      end

      self.terminal_implementation_action = Proc.new { raise exception }
      nil
    end

and_return(first_value, *values) click to toggle source

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

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.

@return [nil] No further chaining is supported after this. @example

    allow(counter).to receive(:count).and_return(1)
    counter.count # => 1
    counter.count # => 1

    allow(counter).to receive(:count).and_return(1,2,3)
    counter.count # => 1
    counter.count # => 2
    counter.count # => 3
    counter.count # => 3
    counter.count # => 3
    # etc

    # File lib/rspec/mocks/message_expectation.rb, line 67
    def and_return(first_value, *values)
      raise_already_invoked_error_if_necessary(__method__)
      if negative?
        raise "`and_return` is not supported with negative message expectations"
      end

      if block_given?
        raise ArgumentError, "Implementation blocks aren't supported with `and_return`"
      end

      values.unshift(first_value)
      @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 && @at_least)
      self.terminal_implementation_action = AndReturnImplementation.new(values)

      nil
    end

and_throw(*args) 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.

@return [nil] No further chaining is supported after this. @example

    allow(car).to receive(:go).and_throw(:out_of_gas)
    allow(car).to receive(:go).and_throw(:out_of_gas, :level => 0.1)

    # File lib/rspec/mocks/message_expectation.rb, line 165
    def and_throw(*args)
      raise_already_invoked_error_if_necessary(__method__)
      self.terminal_implementation_action = Proc.new { throw(*args) }
      nil
    end

and_wrap_original(&block) click to toggle source

Decorates the stubbed method with the supplied block. The original unmodified method is passed to the block along with any method call arguments so you can delegate to it, whilst still being able to change what args are passed to it and/or change the return value.

@note This is only available on partial doubles.

@return [nil] No further chaining is supported after this. @example

    expect(api).to receive(:large_list).and_wrap_original do |original_method, *args, &block|
      original_method.call(*args, &block).first(10)
    end

    # File lib/rspec/mocks/message_expectation.rb, line 113
    def and_wrap_original(&block)
      if RSpec::Mocks::TestDouble === @method_double.object
        @error_generator.raise_only_valid_on_a_partial_double(:and_call_original)
      else
        warn_about_stub_override if implementation.inner_action
        @implementation = AndWrapOriginalImplementation.new(@method_double.original_method, block)
        @yield_receiver_to_implementation_block = false
      end

      nil
    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.

@return [MessageExpecation] self, to support further chaining. @example

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

    # File lib/rspec/mocks/message_expectation.rb, line 177
    def and_yield(*args, &block)
      raise_already_invoked_error_if_necessary(__method__)
      yield @eval_context = Object.new if block
      @args_to_yield << args
      self.initial_implementation_action = AndYieldImplementation.new(@args_to_yield, @eval_context, @error_generator)
      self
    end

at_least(n, &block) click to toggle source

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

@return [MessageExpecation] self, to support further chaining. @example

    expect(dealer).to receive(:deal_card).at_least(9).times

    # File lib/rspec/mocks/message_expectation.rb, line 207
    def at_least(n, &block)
      raise_already_invoked_error_if_necessary(__method__)
      set_expected_received_count :at_least, n

      if n == 0
        raise "at_least(0) has been removed, use allow(...).to receive(:message) instead"
      end

      self.inner_implementation_action = block

      self
    end

at_most(n, &block) click to toggle source

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

@return [MessageExpecation] self, to support further chaining. @example

    expect(dealer).to receive(:deal_card).at_most(10).times

    # File lib/rspec/mocks/message_expectation.rb, line 226
    def at_most(n, &block)
      raise_already_invoked_error_if_necessary(__method__)
      self.inner_implementation_action = block
      set_expected_received_count :at_most, n
      self
    end

exactly(n, &block) click to toggle source

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

@return [MessageExpecation] self, to support further chaining. @example

    expect(dealer).to receive(:deal_card).exactly(10).times

    # File lib/rspec/mocks/message_expectation.rb, line 194
    def exactly(n, &block)
      raise_already_invoked_error_if_necessary(__method__)
      self.inner_implementation_action = block
      set_expected_received_count :exactly, n
      self
    end

never() click to toggle source

Expect a message not to be received at all.

@return [MessageExpecation] self, to support further chaining. @example

    expect(car).to receive(:stop).never

    # File lib/rspec/mocks/message_expectation.rb, line 250
    def never
      ErrorGenerator.raise_double_negation_error("expect(obj)") if negative?
      @expected_received_count = 0
      self
    end

once(&block) click to toggle source

Expect a message to be received exactly one time.

@return [MessageExpecation] self, to support further chaining. @example

    expect(car).to receive(:go).once

    # File lib/rspec/mocks/message_expectation.rb, line 261
    def once(&block)
      self.inner_implementation_action = block
      set_expected_received_count :exactly, 1
      self
    end

ordered(&block) click to toggle source

Expect messages to be received in a specific order.

@return [MessageExpecation] self, to support further chaining. @example

    expect(api).to receive(:prepare).ordered
    expect(api).to receive(:run).ordered
    expect(api).to receive(:finish).ordered

    # File lib/rspec/mocks/message_expectation.rb, line 335
    def ordered(&block)
      self.inner_implementation_action = block
      additional_expected_calls.times do
        @order_group.register(self)
      end
      @ordered = true
      self
    end

thrice(&block) click to toggle source

Expect a message to be received exactly three times.

@return [MessageExpecation] self, to support further chaining. @example

    expect(car).to receive(:go).thrice

    # File lib/rspec/mocks/message_expectation.rb, line 283
    def thrice(&block)
      self.inner_implementation_action = block
      set_expected_received_count :exactly, 3
      self
    end

times(&block) click to toggle source

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

@return [MessageExpecation] self, to support further chaining. @example

    expect(dealer).to receive(:deal_card).exactly(10).times
    expect(dealer).to receive(:deal_card).at_least(10).times
    expect(dealer).to receive(:deal_card).at_most(10).times

    # File lib/rspec/mocks/message_expectation.rb, line 240
    def times(&block)
      self.inner_implementation_action = block
      self
    end

twice(&block) click to toggle source

Expect a message to be received exactly two times.

@return [MessageExpecation] self, to support further chaining. @example

    expect(car).to receive(:go).twice

    # File lib/rspec/mocks/message_expectation.rb, line 272
    def twice(&block)
      self.inner_implementation_action = block
      set_expected_received_count :exactly, 2
      self
    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.

@return [MessageExpecation] self, to support further chaining. @example

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

    expect(cart).to 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 316
    def with(*args, &block)
      raise_already_invoked_error_if_necessary(__method__)
      if args.empty?
        raise ArgumentError,
              "`with` must have at least one argument. Use `no_args` matcher to set the expectation of receiving no arguments."
      end

      self.inner_implementation_action = block
      @argument_list_matcher = ArgumentListMatcher.new(*args)
      self
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.