Module: RSpec::Mocks

Defined in:
lib/rspec/mocks.rb,
lib/rspec/mocks/space.rb,
lib/rspec/mocks/proxy.rb,
lib/rspec/mocks/syntax.rb,
lib/rspec/mocks/version.rb,
lib/rspec/mocks/targets.rb,
lib/rspec/mocks/test_double.rb,
lib/rspec/mocks/order_group.rb,
lib/rspec/mocks/mutate_const.rb,
lib/rspec/mocks/method_double.rb,
lib/rspec/mocks/message_chain.rb,
lib/rspec/mocks/configuration.rb,
lib/rspec/mocks/example_methods.rb,
lib/rspec/mocks/error_generator.rb,
lib/rspec/mocks/verifying_proxy.rb,
lib/rspec/mocks/matchers/receive.rb,
lib/rspec/mocks/object_reference.rb,
lib/rspec/mocks/method_reference.rb,
lib/rspec/mocks/verifying_double.rb,
lib/rspec/mocks/argument_matchers.rb,
lib/rspec/mocks/marshal_extension.rb,
lib/rspec/mocks/any_instance/proxy.rb,
lib/rspec/mocks/any_instance/chain.rb,
lib/rspec/mocks/message_expectation.rb,
lib/rspec/mocks/any_instance/recorder.rb,
lib/rspec/mocks/argument_list_matcher.rb,
lib/rspec/mocks/matchers/have_received.rb,
lib/rspec/mocks/instance_method_stasher.rb,
lib/rspec/mocks/any_instance/stub_chain.rb,
lib/rspec/mocks/matchers/receive_messages.rb,
lib/rspec/mocks/any_instance/message_chains.rb,
lib/rspec/mocks/any_instance/error_generator.rb,
lib/rspec/mocks/any_instance/stub_chain_chain.rb,
lib/rspec/mocks/verifying_message_expectation.rb,
lib/rspec/mocks/any_instance/expectation_chain.rb,
lib/rspec/mocks/matchers/receive_message_chain.rb,
lib/rspec/mocks/any_instance/expect_chain_chain.rb,
lib/rspec/mocks/matchers/expectation_customization.rb

Overview

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

Defined Under Namespace

Modules: ArgumentMatchers, ExampleMethods, Matchers, Syntax, TestDouble, Version Classes: ArgumentListMatcher, Configuration, Constant, ConstantMutator, DirectObjectReference, Double, MessageExpectation, NamedObjectReference, VerifyingMessageExpectation

Constant Summary

MockExpectationError =

Raised when a message expectation is not satisfied.

Class.new(Exception)
ExpiredTestDoubleError =

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

Class.new(MockExpectationError)
OutsideOfExampleError =

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

Class.new(StandardError)
MockExpectationAlreadyInvokedError =

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

Class.new(Exception)
CannotSupportArgMutationsError =
Deprecated.

We no longer raise this error but the constant remains until RSpec 4 for SemVer reasons.

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

Class.new(StandardError)

Class Method Summary (collapse)

Class Method Details

+ (Object) allow_message(subject, message, opts = {}) { ... }

Adds an allowance (stub) on subject

Examples:

Defines the implementation of foo on bar, using the passed block

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

Parameters:

  • subject

    the subject to which the message will be added

  • message

    a symbol, representing the message that will be added.

  • opts (defaults to: {})

    a hash of options, :expected_from is used to set the original call site

Yields:

  • an optional implementation for the allowance

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

+ (Object) configuration

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

199
200
201
# File 'lib/rspec/mocks/configuration.rb', line 199
def self.configuration
  @configuration ||= Configuration.new
end

+ (Object) expect_message(subject, message, opts = {}) { ... }

Sets a message expectation on subject.

Examples:

Expect the message foo to receive bar, then call it

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

Parameters:

  • subject

    the subject on which the message will be expected

  • message

    a symbol, representing the message that will be expected.

  • opts (defaults to: {})

    a hash of options, :expected_from is used to set the original call site

Yields:

  • an optional implementation for the expectation

84
85
86
# File '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

+ (Object) setup

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

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

+ (Object) 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.

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

+ (Object) verify

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

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

+ (Object) 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.

90
91
92
93
94
95
96
97
98
99
# File 'lib/rspec/mocks.rb', line 90
def self.with_temporary_scope
  setup
  begin
    yield
    verify
  ensure
    teardown
  end
end