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

- (String, Object) actual

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 82

- (String) description

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

- (Boolean) diffable?

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 76

- (Boolean) does_not_match?(actual) { ... }

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

- (String, Object) expected

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 89

- (Boolean) expects_call_stack_jump?

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 63

- (String) failure_message

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

Returns:

  • (String)

    Explanation for the failure.


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

- (String) failure_message_when_negated

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

- (Boolean) matches?(actual) { ... }

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

- (Boolean) supports_block_expectations?

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