module RSpec::Mocks

Contains top-level utility methods. While this contains a few public methods, these are not generally meant to be called from a test or example. They exist primarily for integration with test frameworks (such as rspec-core).

Constants

CannotSupportArgMutationsError

Raised for situations that RSpec cannot support due to mutations made externally on arguments that RSpec is holding onto to use for later comparisons.

@deprecated We no longer raise this error but the constant remains until

RSpec 4 for SemVer reasons.

DEFAULT_CALLBACK_INVOCATION_STRATEGY

@private

ExpiredTestDoubleError

Raised when a test double is used after it has been torn down (typically at the end of an rspec-core example).

IGNORED_BACKTRACE_LINE

@private

MockExpectationAlreadyInvokedError

Raised when an expectation customization method (e.g. ‘with`, `and_return`) is called on a message expectation which has already been invoked.

MockExpectationError

Raised when a message expectation is not satisfied.

NegationUnsupportedError

@private

OutsideOfExampleError

Raised when doubles or partial doubles are used outside of the per-test lifecycle.

UnsupportedMatcherError

@private

VerifyingDoubleNotDefinedError

@private

Attributes

space [R]

@private

Public Class Methods

allow_message (subject, message, opts={}, &block)

Adds an allowance (stub) on ‘subject`

@param subject the subject to which the message will be added @param message a symbol, representing the message that will be

added.

@param opts a hash of options, :expected_from is used to set the

original call site

@yield an optional implementation for the allowance

@example Defines the implementation of ‘foo` on `bar`, using the passed block

x = 0
RSpec::Mocks.allow_message(bar, :foo) { x += 1 }

# File rspec-mocks/lib/rspec/mocks.rb, line 69
def self.allow_message(subject, message, opts={}, &block)
  space.proxy_for(subject).add_stub(message, opts, &block)
end

configuration ()

Mocks specific configuration, as distinct from ‘RSpec.configuration` which is core RSpec configuration.

# File rspec-mocks/lib/rspec/mocks/configuration.rb, line 206
def self.configuration
  @configuration ||= Configuration.new
end

error_generator ()

@private

# File rspec-mocks/lib/rspec/mocks/error_generator.rb, line 386
def self.error_generator
  @error_generator ||= ErrorGenerator.new
end

expect_message (subject, message, opts={}, &block)

Sets a message expectation on ‘subject`. @param subject the subject on which the message will be expected @param message a symbol, representing the message that will be

expected.

@param opts a hash of options, :expected_from is used to set the

original call site

@yield an optional implementation for the expectation

@example Expect the message ‘foo` to receive `bar`, then call it

RSpec::Mocks.expect_message(bar, :foo)
bar.foo

# File rspec-mocks/lib/rspec/mocks.rb, line 84
def self.expect_message(subject, message, opts={}, &block)
  space.proxy_for(subject).add_message_expectation(message, opts, &block)
end

setup ()

Performs per-test/example setup. This should be called before an test or example begins.

# File rspec-mocks/lib/rspec/mocks.rb, line 38
def self.setup
  @space_stack << (@space = space.new_scope)
end

teardown ()

Cleans up all test double state (including any methods that were redefined on partial doubles). This must be called after each example, even if an error was raised during the example.

# File rspec-mocks/lib/rspec/mocks.rb, line 51
def self.teardown
  space.reset_all
  @space_stack.pop
  @space = @space_stack.last || @root_space
end

verify ()

Verifies any message expectations that were set during the test or example. This should be called at the end of an example.

# File rspec-mocks/lib/rspec/mocks.rb, line 44
def self.verify
  space.verify_all
end

with_temporary_scope () { || ... }

Call the passed block and verify mocks after it has executed. This allows mock usage in arbitrary places, such as a ‘before(:all)` hook.

@return [Object] the return value from the block

# File rspec-mocks/lib/rspec/mocks.rb, line 92
def self.with_temporary_scope
  setup

  begin
    result = yield
    verify
    result
  ensure
    teardown
  end
end