Class: RSpec::Matchers::MatcherProtocol

Inherits:

Object

• Object
• RSpec::Matchers::MatcherProtocol

Defined in:

lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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

• #failure_message ⇒ String

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

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

  True if this matcher matches the provided object.

Optional Methods

• #actual ⇒ String, Object

  The actual value for the purposes of a diff.

• #description ⇒ String

  The description is used for two things:.

• #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.

• #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.

• #expected ⇒ String, Object

  The expected value for the purposes of a diff.

• #expects_call_stack_jump? ⇒ Boolean

  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).

• #failure_message_when_negated ⇒ String

  This will only be called when a negative match fails.

• #supports_block_expectations? ⇒ Boolean

  Indicates that this matcher can be used in a block expectation expression, such as ‘expect { foo }.to raise_error`.

• #supports_value_expectations? ⇒ Boolean

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

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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/matcher_protocol.rb', line 63