Module: RSpec::Mocks

Defined in:
lib/rspec/mocks.rb,
lib/rspec/mocks/proxy.rb,
lib/rspec/mocks/space.rb,
lib/rspec/mocks/syntax.rb,
lib/rspec/mocks/targets.rb,
lib/rspec/mocks/version.rb,
lib/rspec/mocks/order_group.rb,
lib/rspec/mocks/test_double.rb,
lib/rspec/mocks/mutate_const.rb,
lib/rspec/mocks/configuration.rb,
lib/rspec/mocks/message_chain.rb,
lib/rspec/mocks/method_double.rb,
lib/rspec/mocks/error_generator.rb,
lib/rspec/mocks/example_methods.rb,
lib/rspec/mocks/verifying_proxy.rb,
lib/rspec/mocks/matchers/receive.rb,
lib/rspec/mocks/method_reference.rb,
lib/rspec/mocks/object_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/chain.rb,
lib/rspec/mocks/any_instance/proxy.rb,
lib/rspec/mocks/message_expectation.rb,
lib/rspec/mocks/minitest_integration.rb,
lib/rspec/mocks/minitest_integration.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/any_instance/stub_chain.rb,
lib/rspec/mocks/instance_method_stasher.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 collapse

MockExpectationError =

Raised when a message expectation is not satisfied.

::Minitest::Assertion
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

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

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

.configuration ⇒ Object

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



206
207
208
 
# File 'lib/rspec/mocks/configuration.rb', line 206

def self.configuration
  @configuration ||= Configuration.new
end

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

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

.setup ⇒ Object

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

.teardown ⇒ Object

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

.verify ⇒ Object

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

.with_temporary_scope ⇒ Object

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

Returns:

  • (Object) —

    the return value from the block



92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/rspec/mocks.rb', line 92

def self.with_temporary_scope
  setup

  begin
    result = yield
    verify
    result
  ensure
    teardown
  end
end