Module: RSpec::Mocks::ExampleMethods

Includes:
ArgumentMatchers
Defined in:
lib/rspec/mocks/example_methods.rb

Overview

Contains methods intended to be used from within code examples. Mix this in to your test context (such as a test framework base class) to use rspec-mocks with your test framework. If you're using rspec-core, it'll take care of doing this for you.

Defined Under Namespace

Modules: ExpectHost

Instance Method Summary collapse

Methods included from ArgumentMatchers

#any_args, #anything, #array_including, #boolean, #duck_type, #hash_excluding, #hash_including, #instance_of, #kind_of, #no_args

Instance Method Details

#allowObject

Note:

If you disable the :expect syntax this method will be undefined.

Used to wrap an object in preparation for stubbing a method on it.

Examples:

allow(dbl).to receive(:foo).with(5).and_return(:return_value)


# File 'lib/rspec/mocks/example_methods.rb', line 296

#allow_any_instance_ofObject

Note:

This is only available when you have enabled the expect syntax.

Used to wrap a class in preparation for stubbing a method on instances of it.

Examples:

allow_any_instance_of(MyClass).to receive(:foo)


# File 'lib/rspec/mocks/example_methods.rb', line 314

#allow_message_expectations_on_nilObject

Disables warning messages about expectations being set on nil.

By default warning messages are issued when expectations are set on nil. This is to prevent false-positives and to catch potential bugs early on.



200
201
202
# File 'lib/rspec/mocks/example_methods.rb', line 200

def allow_message_expectations_on_nil
  RSpec::Mocks.space.proxy_for(nil).warn_about_expectations = false
end

#class_double(doubled_class) ⇒ Object #class_double(doubled_class, name) ⇒ Object #class_double(doubled_class, stubs) ⇒ Object #class_double(doubled_class, name, stubs) ⇒ Object

Constructs a test double against a specific class. If the given class name has been loaded, only class methods defined on the class are allowed to be stubbed. In all other ways it behaves like a double.



79
80
81
82
# File 'lib/rspec/mocks/example_methods.rb', line 79

def class_double(doubled_class, *args)
  ref = ObjectReference.for(doubled_class)
  ExampleMethods.declare_verifying_double(ClassVerifyingDouble, ref, *args)
end

#class_spy(doubled_class) ⇒ Object #class_spy(doubled_class, name) ⇒ Object #class_spy(doubled_class, stubs) ⇒ Object #class_spy(doubled_class, name, stubs) ⇒ Object

Constructs a test double that is optimized for use with have_received against a specific class. If the given class name has been loaded, only class methods defined on the class are allowed to be stubbed. With a normal double one has to stub methods in order to be able to spy them. An class_spy automatically spies on all class methods to which the class responds.



191
192
193
# File 'lib/rspec/mocks/example_methods.rb', line 191

def class_spy(*args)
  class_double(*args).as_null_object
end

#doubleDouble #double(name) ⇒ Double #double(stubs) ⇒ Double #double(name, stubs) ⇒ Double

Constructs an instance of RSpec::Mocks::Double configured with an optional name, used for reporting in failure messages, and an optional hash of message/return-value pairs.

Examples:

book = double("book", :title => "The RSpec Book")
book.title #=> "The RSpec Book"

card = double("card", :suit => "Spades", :rank => "A")
card.suit  #=> "Spades"
card.rank  #=> "A"


34
35
36
# File 'lib/rspec/mocks/example_methods.rb', line 34

def double(*args)
  ExampleMethods.declare_double(Double, *args)
end

#expectObject

Note:

This method is usually provided by rspec-expectations. However, if you use rspec-mocks without rspec-expectations, there's a definition of it that is made available here. If you disable the :expect syntax this method will be undefined.

Used to wrap an object in preparation for setting a mock expectation on it.

Examples:

expect(obj).to receive(:foo).with(5).and_return(:return_value)


# File 'lib/rspec/mocks/example_methods.rb', line 284

#expect_any_instance_ofObject

Note:

If you disable the :expect syntax this method will be undefined.

Used to wrap a class in preparation for setting a mock expectation on instances of it.

Examples:

expect_any_instance_of(MyClass).to receive(:foo)


# File 'lib/rspec/mocks/example_methods.rb', line 305

#have_received(method_name, &block) ⇒ Object

Note:

have_received(...).with(...) is unable to work properly when passed arguments are mutated after the spy records the received message.

Verifies that the given object received the expected message during the course of the test. On a spy objects or as null object doubles this works for any method, on other objects the method must have been stubbed beforehand in order for messages to be verified.

Stubbing and verifying messages received in this way implements the Test Spy pattern.

Examples:

invitation = double('invitation', accept: true)
user.accept_invitation(invitation)
expect(invitation).to have_received(:accept)

# You can also use most message expectations:
expect(invitation).to have_received(:accept).with(mailer).once


280
281
282
# File 'lib/rspec/mocks/example_methods.rb', line 280

def have_received(method_name, &block)
  Matchers::HaveReceived.new(method_name, &block)
end

#hide_const(constant_name) ⇒ Object

Hides the named constant with the given value. The constant will be undefined for the duration of the test.

Like method stubs, the constant will be restored to its original value when the example completes.

Examples:

hide_const("MyClass") # => MyClass is now an undefined constant


255
256
257
# File 'lib/rspec/mocks/example_methods.rb', line 255

def hide_const(constant_name)
  ConstantMutator.hide(constant_name)
end

#instance_double(doubled_class) ⇒ Object #instance_double(doubled_class, name) ⇒ Object #instance_double(doubled_class, stubs) ⇒ Object #instance_double(doubled_class, name, stubs) ⇒ Object

Constructs a test double against a specific class. If the given class name has been loaded, only instance methods defined on the class are allowed to be stubbed. In all other ways it behaves like a double.



56
57
58
59
# File 'lib/rspec/mocks/example_methods.rb', line 56

def instance_double(doubled_class, *args)
  ref = ObjectReference.for(doubled_class)
  ExampleMethods.declare_verifying_double(InstanceVerifyingDouble, ref, *args)
end

#instance_spy(doubled_class) ⇒ Object #instance_spy(doubled_class, name) ⇒ Object #instance_spy(doubled_class, stubs) ⇒ Object #instance_spy(doubled_class, name, stubs) ⇒ Object

Constructs a test double that is optimized for use with have_received against a specific class. If the given class name has been loaded, only instance methods defined on the class are allowed to be stubbed. With a normal double one has to stub methods in order to be able to spy them. An instance_spy automatically spies on all instance methods to which the class responds.



144
145
146
# File 'lib/rspec/mocks/example_methods.rb', line 144

def instance_spy(*args)
  instance_double(*args).as_null_object
end

#object_double(object_or_name) ⇒ Object #object_double(object_or_name, name) ⇒ Object #object_double(object_or_name, stubs) ⇒ Object #object_double(object_or_name, name, stubs) ⇒ Object

Constructs a test double against a specific object. Only the methods the object responds to are allowed to be stubbed. If a String argument is provided, it is assumed to reference a constant object which is used for verification. In all other ways it behaves like a double.



102
103
104
105
# File 'lib/rspec/mocks/example_methods.rb', line 102

def object_double(object_or_name, *args)
  ref = ObjectReference.for(object_or_name, :allow_direct_object_refs)
  ExampleMethods.declare_verifying_double(ObjectVerifyingDouble, ref, *args)
end

#object_spy(object_or_name) ⇒ Object #object_spy(object_or_name, name) ⇒ Object #object_spy(object_or_name, stubs) ⇒ Object #object_spy(object_or_name, name, stubs) ⇒ Object

Constructs a test double that is optimized for use with have_received against a specific object. Only instance methods defined on the object are allowed to be stubbed. With a normal double one has to stub methods in order to be able to spy them. An object_spy automatically spies on all methods to which the object responds.



167
168
169
# File 'lib/rspec/mocks/example_methods.rb', line 167

def object_spy(*args)
  object_double(*args).as_null_object
end

#receiveObject

Note:

If you disable the :expect syntax this method will be undefined.

Used to specify a message that you expect or allow an object to receive. The object returned by receive supports the same fluent interface that should_receive and stub have always supported, allowing you to constrain the arguments or number of times, and configure how the object should respond to the message.

Examples:

expect(obj).to receive(:hello).with("world").exactly(3).times


# File 'lib/rspec/mocks/example_methods.rb', line 323

#receive_message_chain(method1, method2) ⇒ Object #receive_message_chain("method1.method2") ⇒ Object #receive_message_chain(method1, method_to_value_hash) ⇒ Object

Note:

If you disable the :expect syntax this method will be undefined.

stubs/mocks a chain of messages on an object or test double.

Warning:

Chains can be arbitrarily long, which makes it quite painless to violate the Law of Demeter in violent ways, so you should consider any use of receive_message_chain a code smell. Even though not all code smells indicate real problems (think fluent interfaces), receive_message_chain still results in brittle examples. For example, if you write allow(foo).to receive_message_chain(:bar, :baz => 37) in a spec and then the implementation calls foo.baz.bar, the stub will not work.

Examples:

allow(double).to receive_message_chain("foo.bar") { :baz }
allow(double).to receive_message_chain(:foo, :bar => :baz)
allow(double).to receive_message_chain(:foo, :bar) { :baz }

# Given any of ^^ these three forms ^^:
double.foo.bar # => :baz

# Common use in Rails/ActiveRecord:
allow(Article).to receive_message_chain("recent.published") { [Article.new] }


# File 'lib/rspec/mocks/example_methods.rb', line 348

#receive_messagesObject

Note:

If you disable the :expect syntax this method will be undefined.

Shorthand syntax used to setup message(s), and their return value(s), that you expect or allow an object to receive. The method takes a hash of messages and their respective return values. Unlike with receive, you cannot apply further customizations using a block or the fluent interface.

Examples:

allow(obj).to receive_messages(:speak => "Hello World")
allow(obj).to receive_messages(:speak => "Hello", :meow => "Meow")


# File 'lib/rspec/mocks/example_methods.rb', line 335

#spyDouble #spy(name) ⇒ Double #spy(stubs) ⇒ Double #spy(name, stubs) ⇒ Double

Constructs a test double that is optimized for use with have_received. With a normal double one has to stub methods in order to be able to spy them. A spy automatically spies on all methods.



120
121
122
# File 'lib/rspec/mocks/example_methods.rb', line 120

def spy(*args)
  double(*args).as_null_object
end

#stub_const(constant_name, value, options = {}) ⇒ Object

Stubs the named constant with the given value. Like method stubs, the constant will be restored to its original value (or lack of one, if it was undefined) when the example completes.

Examples:

stub_const("MyClass", Class.new) # => Replaces (or defines) MyClass with a new class object.
stub_const("SomeModel::PER_PAGE", 5) # => Sets SomeModel::PER_PAGE to 5.

class CardDeck
  SUITS = [:Spades, :Diamonds, :Clubs, :Hearts]
  NUM_CARDS = 52
end

stub_const("CardDeck", Class.new)
CardDeck::SUITS # => uninitialized constant error
CardDeck::NUM_CARDS # => uninitialized constant error

stub_const("CardDeck", Class.new, :transfer_nested_constants => true)
CardDeck::SUITS # => our suits array
CardDeck::NUM_CARDS # => 52

stub_const("CardDeck", Class.new, :transfer_nested_constants => [:SUITS])
CardDeck::SUITS # => our suits array
CardDeck::NUM_CARDS # => uninitialized constant error

Options Hash (options):

  • :transfer_nested_constants (Boolean, Array<Symbol>)

    Determines what nested constants, if any, will be transferred from the original value of the constant to the new value of the constant. This only works if both the original and new values are modules (or classes).



240
241
242
# File 'lib/rspec/mocks/example_methods.rb', line 240

def stub_const(constant_name, value, options={})
  ConstantMutator.stub(constant_name, value, options)
end