Module: RSpec::Mocks

Defined in:
lib/rspec/mocks.rb,
lib/rspec/mocks/mock.rb,
lib/rspec/mocks/proxy.rb,
lib/rspec/mocks/space.rb,
lib/rspec/mocks/syntax.rb,
lib/rspec/mocks/errors.rb,
lib/rspec/mocks/targets.rb,
lib/rspec/mocks/version.rb,
lib/rspec/mocks/stub_chain.rb,
lib/rspec/mocks/deprecation.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/proxy_for_nil.rb,
lib/rspec/mocks/configuration.rb,
lib/rspec/mocks/error_generator.rb,
lib/rspec/mocks/example_methods.rb,
lib/rspec/mocks/matchers/receive.rb,
lib/rspec/mocks/argument_matchers.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/any_instance/stub_chain.rb,
lib/rspec/mocks/instance_method_stasher.rb,
lib/rspec/mocks/extensions/instance_exec.rb,
lib/rspec/mocks/any_instance/message_chains.rb,
lib/rspec/mocks/any_instance/stub_chain_chain.rb,
lib/rspec/mocks/any_instance/expectation_chain.rb

Defined Under Namespace

Modules: AnyInstance, ArgumentMatchers, Deprecation, ExampleMethods, Matchers, RecursiveConstMethods, Syntax, TestDouble, Version Classes: AllowanceTarget, AnyInstanceAllowanceTarget, AnyInstanceExpectationTarget, ArgumentListMatcher, Configuration, Constant, ConstantMutator, ExpectationTarget, MessageExpectation, Mock, Space, TargetBase

Constant Summary

KERNEL_METHOD_METHOD =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

::Kernel.instance_method(:method)
UnsupportedMatcherError = 
Class.new(StandardError)
NegationUnsupportedError = 
Class.new(StandardError)
ConstantStubber =

Keeps backwards compatibility since we had released an rspec-mocks that only supported stubbing. Later, we released the hide_const feature and decided that the term "mutator" was a better term to wrap up the concept of both stubbing and hiding.

ConstantMutator

Class Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Attribute Details

+ (Object) space

Returns the value of attribute space

8
9
10
 
# File 'lib/rspec/mocks.rb', line 8
def space
  @space
end

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

  • block —

    an optional implementation for the allowance

49
50
51
52
53
 
# File 'lib/rspec/mocks.rb', line 49
def allow_message(subject, message, opts={}, &block)
  orig_caller = opts.fetch(:expected_from) { caller(1)[0] }
  ::RSpec::Mocks.proxy_for(subject).
    add_stub(orig_caller, message.to_sym, opts, &block)
end

+ (Object) any_instance_recorder_for(klass) 

33
34
35
 
# File 'lib/rspec/mocks.rb', line 33
def any_instance_recorder_for(klass)
  space.any_instance_recorder_for(klass)
end

+ (Object) configuration 

48
49
50
 
# File 'lib/rspec/mocks/configuration.rb', line 48
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

  • block —

    an optional implementation for the expectation

66
67
68
69
70
 
# File 'lib/rspec/mocks.rb', line 66
def expect_message(subject, message, opts={}, &block)
  orig_caller = opts.fetch(:expected_from) { caller(1)[0] }
  ::RSpec::Mocks.proxy_for(subject).
    add_message_expectation(orig_caller, message.to_sym, opts, &block)
end

+ (Object) method_handle_for(object, method_name)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Used internally to get a method handle for a particular object and method name.

Includes handling for a few special cases:

  • Objects that redefine #method (e.g. an HTTPRequest struct)
  • BasicObject subclasses that mixin a Kernel dup (e.g. SimpleDelegator)
83
84
85
86
87
88
89
 
# File 'lib/rspec/mocks.rb', line 83
def method_handle_for(object, method_name)
  if ::Kernel === object
    KERNEL_METHOD_METHOD.bind(object).call(method_name)
  else
    object.method(method_name)
  end
end

+ (Object) proxies_of(klass) 

29
30
31
 
# File 'lib/rspec/mocks.rb', line 29
def proxies_of(klass)
  space.proxies_of(klass)
end

+ (Object) proxy_for(object) 

25
26
27
 
# File 'lib/rspec/mocks.rb', line 25
def proxy_for(object)
  space.proxy_for(object)
end

+ (Object) setup(host) 

10
11
12
13
14
15
 
# File 'lib/rspec/mocks.rb', line 10
def setup(host)
  (class << host; self; end).class_eval do
    include RSpec::Mocks::ExampleMethods
  end
  self.space ||= RSpec::Mocks::Space.new
end

+ (Object) teardown 

21
22
23
 
# File 'lib/rspec/mocks.rb', line 21
def teardown
  space.reset_all
end

+ (Object) verify 

17
18
19
 
# File 'lib/rspec/mocks.rb', line 17
def verify
  space.verify_all
end

Instance Method Details

- (Object) allow

Note:

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

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/syntax.rb', line 304


    		
  





      

  

    - (Object) allow_any_instance_of 


  

  

    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/syntax.rb', line 324


    		
  





      

  

    - (Recorder) any_instance 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Used to set stubs and message expectations on any instance of a given
class. Returns a Recorder, which records messages like
stub and should_receive for later playback on instances of the
class.

  





  

    
Examples:

      
Car.any_instance.should_receive(:go)
race = Race.new
race.cars << Car.new
race.go # assuming this delegates to all of its cars
        # this example would pass

Account.any_instance.stub(:balance) { Money.new(:USD, 25) }
Account.new.balance # => Money.new(:USD, 25))

  


Returns:


    
    
  • 
        (Recorder)
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 271


    		
  





      

  

    - (Object) as_null_object 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Tells the object to respond to all messages. If specific stub values
are declared, they'll work as expected. If not, the receiver is
returned.

  







  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 259


    		
  





      

  

    - (Object) expect 


  

  

    Note:
    
This method is usually provided by rspec-expectations, unless
you are using rspec-mocks w/o rspec-expectations, in which case it
is only made available if you enable the expect syntax.



  


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/syntax.rb', line 292


    		
  





      

  

    - (Object) expect_any_instance_of 


  

  

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



  


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/syntax.rb', line 314


    		
  





      

  

    - (Object) null_object? 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Returns true if this object has received as_null_object

  







  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 266


    		
  





      

  

    - (Object) receive 


  

  

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



  


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/syntax.rb', line 334


    		
  





      

  

    - (Object) should_not_receive 


  

    
Sets and expectation that this object should not receive a message
during this example.

  







  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 202


    		
  





      

  

    - (Object) should_receive 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Sets an expectation that this object should receive a message before
the end of the example.

  





  

    
Examples:

      
logger = double('logger')
thing_that_logs = ThingThatLogs.new(logger)
logger.should_receive(:log)
thing_that_logs.do_something_that_logs_a_message

  



  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 189


    		
  





      

  

    - (Object) stub 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Tells the object to respond to the message with the specified value.

  





  

    
Examples:

      
counter.stub(:count).and_return(37)
counter.stub(:count => 37)
counter.stub(:count) { 37 }

  



  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 206


    		
  





      

  

      - (Object) stub_chain(method1, method2) 
      - (Object) stub_chain("method1.method2") 
      - (Object) stub_chain(method1, method_to_value_hash) 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Stubs a chain of methods.


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 stub_chain a code smell. Even though not all code smells
indicate real problems (think fluent interfaces), stub_chain still
results in brittle examples.  For example, if you write
foo.stub_chain(:bar, :baz => 37) in a spec and then the
implementation calls foo.baz.bar, the stub will not work.

  





  

    
Examples:

      
double.stub_chain("foo.bar") { :baz }
double.stub_chain(:foo, :bar => :baz)
double.stub_chain(:foo, :bar) { :baz }
# Given any of ^^ these three forms ^^:
double.foo.bar # => :baz

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

  



  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 228


    		
  





      

  

    - (Object) unstub 


  

  

    Note:
    
This is only available when you have enabled the should syntax.



  


Removes a stub. On a double, the object will no longer respond to
message. On a real object, the original method (if it exists) is
restored.


This is rarely used, but can be useful when a stub is set up during a
shared before hook for the common case, but you want to replace it
for a special case.

  







  

    
      

    		
    
      
# File 'lib/rspec/mocks/syntax.rb', line 217