Class: RSpec::Matchers::MatcherProtocol

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/matchers/matcher_protocol.rb

Overview

Note:

This class is not loaded at runtime by rspec-expectations. It exists purely to provide documentation for the matcher protocol.

rspec-expectations can work with any matcher object that implements this protocol.

Required Methods collapse

Optional Methods collapse

Instance Method Details

#actual ⇒ String, Object

Note:

This method is required if diffable? returns true.

The actual value for the purposes of a diff.

Returns:

  • (String, Object) —

    If an object (rather than a string) is provided, RSpec will use the pp library to convert it to multi-line output in order to diff.


    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 88


    		
  





      

  

    #description  ⇒ String 


  

    
The description is used for two things:


    

  • When using RSpec's one-liner syntax
(e.g. it { is_expected.to matcher }), the description
is used to generate the example's doc string since you
have not provided one.
    • 

  • In a composed matcher expression, the description is used
as part of the failure message (and description) of the outer
matcher.
    • 


  






Returns:


    
    
  • 
        (String)
        —
        
    Description of the matcher.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 42


    		
  





      

  

    #diffable?  ⇒ Boolean 


  

    
Indicates that this matcher provides actual and expected attributes,
and that the values returned by these can be usefully diffed, which can
be included in the output.

  






Returns:


    
    
  • 
        (Boolean)
        —
        
    true if actual and expected can be diffed.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 82


    		
  





      

  

    #does_not_match?(actual) { ... } ⇒ Boolean 


  

    
In a negative expectation such as expect(x).not_to foo, RSpec will
call foo.does_not_match?(x) if this method is defined. If it's not
defined it will fall back to using !foo.matches?(x). This allows you
to provide custom logic for the negative case.

  





  
Parameters:


    
    
  • 
        actual
        (Object)
        —
        
    The object being matched against.
    

    
    
    • 



Yields:


    
    
  • 
        
        
    For an expression like expect(x).not_to matcher do...end, the do/end
block binds to not_to. It passes that block, if there is one, on to this method.
    

    
    
    • 



Returns:


    
    
  • 
        (Boolean)
        —
        
    true if this matcher does not match the provided object.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 24


    		
  





      

  

    #expected  ⇒ String, Object 


  

  

    Note:
    
This method is required if diffable? returns true.



  


The expected value for the purposes of a diff.

  






Returns:


    
    
  • 
        (String, Object)
        —
        
    If an object (rather than a string) is provided,
RSpec will use the pp library to convert it to multi-line output in
order to diff.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 95


    		
  





      

  

    #expects_call_stack_jump?  ⇒ Boolean 


  

  

    Note:
    
This method is very rarely used or needed.



  

  

    Note:
    
If not defined, RSpec assumes a value of false for this method.



  


Indicates that when this matcher is used in a block expectation
expression, it expects the block to use a ruby construct that causes
a call stack jump (such as raising an error or throwing a symbol).


This is used internally for compound block expressions, as matchers
which expect call stack jumps must be treated with care to work properly.

  






Returns:


    
    
  • 
        (Boolean)
        —
        
    true if the matcher expects a call stack jump
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 69


    		
  





      

  

    #failure_message  ⇒ String 


  

    
This will only be called if #matches? returns false.

  






Returns:


    
    
  • 
        (String)
        —
        
    Explanation for the failure.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 16


    		
  





      

  

    #failure_message_when_negated  ⇒ String 


  

  

    Note:
    
This method is listed as optional because matchers do not have to
support negation. But if your matcher does support negation, this is a
required method -- otherwise, you'll get a NoMethodError.



  


This will only be called when a negative match fails.

  






Returns:


    
    
  • 
        (String)
        —
        
    Explanation for the failure.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 35


    		
  





      

  

    #matches?(actual) { ... } ⇒ Boolean 


  

    
Returns true if this matcher matches the provided object.

  





  
Parameters:


    
    
  • 
        actual
        (Object)
        —
        
    The object being matched against.
    

    
    
    • 



Yields:


    
    
  • 
        
        
    For an expression like expect(x).to matcher do...end, the do/end
block binds to to. It passes that block, if there is one, on to this method.
    

    
    
    • 



Returns:


    
    
  • 
        (Boolean)
        —
        
    true if this matcher matches the provided object.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 10


    		
  





      

  

    #supports_block_expectations?  ⇒ Boolean 


  

  

    Note:
    
If not defined, RSpec assumes a value of false for this method.



  


Indicates that this matcher can be used in a block expectation expression,
such as expect { foo }.to raise_error. Generally speaking, this is
only needed for matchers which operate on a side effect of a block, rather
than on a particular object.

  






Returns:


    
    
  • 
        (Boolean)
        —
        
    true if this matcher can be used in block expressions.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 55


    		
  





      

  

    #supports_value_expectations?  ⇒ Boolean 


  

  

    Note:
    
If not defined, RSpec assumes a value of true for this method.



  


Indicates that this matcher can be used in a value expectation expression,
such as expect(foo).to eq(bar).

  






Returns:


    
    
  • 
        (Boolean)
        —
        
    true if this matcher can be used in value expressions.
    

    
    
    • 




  

    
      

    		
    
      
# File 'lib/rspec/matchers/matcher_protocol.rb', line 63