Class: RSpec::Matchers::DSL::Matcher

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Macros::Deprecated`, `Macros`
Instance Chain: self, `::RSpec::Matchers::Composable`, `::RSpec::Matchers`, `DefaultImplementations`, `::RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages`
Inherits:	Object
Defined in:	rspec-expectations/lib/rspec/matchers/dsl.rb

Overview

The class used for custom matchers. The block passed to RSpec::Matchers.define will be evaluated in the context of the singleton class of an instance, and will have the Macros methods available.

Constant Summary

`::RSpec::Matchers` - Included

BE_PREDICATE_REGEX, DYNAMIC_MATCHER_REGEX, HAS_REGEX

Class Method Summary

.new(name, declarations, matcher_execution_context, *expected, &block_arg) ⇒ Matcher constructor Internal use only Internal use only

`Macros::Deprecated` - Extended

failure_message_for_should, failure_message_for_should_not, match_for_should, match_for_should_not

`Macros` - Extended

chain	Convenience for defining methods on this matcher to create a fluent interface.
description	Customize the description to use for one-liners.
diffable	Tells the matcher to diff the actual and expected values in the failure message.
failure_message	Customizes the failure message to use when this matcher is asked to positively match.
failure_message_when_negated	Customize the failure message to use when this matcher is asked to negatively match.
match	Stores the block that is used to determine whether this matcher passes or fails.
match_unless_raises	Use this instead of RSpec::Matchers#match when the block will raise an exception rather than returning false to indicate a failure.
match_when_negated	Use this to define the block for a negative expectation (‘expect(…).not_to`) when the positive and negative forms require different handling.
supports_block_expectations	Declares that the matcher can be used in a block expectation.
assign_attributes,
define_user_override	Does the following:

Instance Attribute Summary

#actual readonly

Exposes the value being matched against – generally the object object wrapped by RSpec::Matchers#expect.
#block_arg readonly

The block parameter used in the expectation.
#expected_as_array readonly

Returns the expected value as an an array.
#name readonly

The name of the matcher.
#rescued_exception readonly

Exposes the exception raised during the matching by match_unless_raises.

`DefaultImplementations` - Included

#diffable?	Used internally by objects returns by `should` and `should_not`.
#expects_call_stack_jump?	Most matchers do not expect call stack jumps.
#supports_block_expectations?	`::RSpec::Matchers` do not support block expectations by default.
#supports_value_expectations?

Instance Method Summary

#expected

Provides the expected value.
#inspect

Adds the name (rather than a cryptic hex number) so we can identify an instance of the matcher in error messages (e.g.
#respond_to?(method, include_private = false) ⇒ Boolean

:nocov: Indicates that this matcher responds to messages from the @matcher_execution_context as well.
#respond_to_missing?(method, include_private = false) ⇒ Boolean

Indicates that this matcher responds to messages from the @matcher_execution_context as well.
#actual_arg_for(block) private
#method_missing(method, *args, &block) private

Takes care of forwarding unhandled messages to the @matcher_execution_context (typically the current running ::RSpec::Core::Example).

`::RSpec::Matchers::Composable` - Included

#&	Alias for Composable#and.
#===	Delegates to `#matches?`.
#and	Creates a compound `and` expectation.
#description_of	Returns the description of the given object in a way that is aware of composed matchers.
#or	Creates a compound `or` expectation.
#values_match?	This provides a generic way to fuzzy-match an expected value against an actual value.
#\|	Alias for Composable#or.
#should_enumerate?	We should enumerate arrays as long as they are not recursive.
#surface_descriptions_in	Transforms the given data structure (typically a hash or array) into a new data structure that, when #inspect is called on it, will provide descriptions of any contained matchers rather than the normal #inspect output.
#unreadable_io?,
#with_matchers_cloned	Historically, a single matcher instance was only checked against a single value.

`::RSpec::Matchers` - Included

#a_block_changing	Alias for RSpec::Matchers#change.
#a_block_outputting	Alias for RSpec::Matchers#output.
#a_block_raising	Alias for RSpec::Matchers#raise_error.
#a_block_throwing	Alias for RSpec::Matchers#throw_symbol.
#a_block_yielding_control	Alias for RSpec::Matchers#yield_control.
#a_block_yielding_successive_args	Alias for RSpec::Matchers#yield_successive_args.
#a_block_yielding_with_args	Alias for RSpec::Matchers#yield_with_args.
#a_block_yielding_with_no_args	Alias for RSpec::Matchers#yield_with_no_args.
#a_collection_containing_exactly	Alias for RSpec::Matchers#contain_exactly.
#a_collection_ending_with	Alias for RSpec::Matchers#end_with.
#a_collection_including	Alias for RSpec::Matchers#include.
#a_collection_starting_with	Alias for RSpec::Matchers#start_with.
#a_falsey_value	Alias for RSpec::Matchers#be_falsey.
#a_falsy_value	Alias for RSpec::Matchers#be_falsey.
#a_hash_including	Alias for RSpec::Matchers#include.
#a_kind_of	Alias for RSpec::Matchers#be_a_kind_of.
#a_nil_value	Alias for RSpec::Matchers#be_nil.
#a_range_covering	Alias for RSpec::Matchers#cover.
#a_string_ending_with	Alias for RSpec::Matchers#end_with.
#a_string_including	Alias for RSpec::Matchers#include.
#a_string_matching	Alias for RSpec::Matchers#match.
#a_string_starting_with	Alias for RSpec::Matchers#start_with.
#a_truthy_value	Alias for RSpec::Matchers#be_truthy.
#a_value	Alias for RSpec::Matchers#be.
#a_value_between	Alias for RSpec::Matchers#be_between.
#a_value_within	Alias for RSpec::Matchers#be_within.
#aggregate_failures	Allows multiple expectations in the provided block to fail, and then aggregates them into a single exception, rather than aborting on the first expectation failure like normal.
#all	Passes if the provided matcher passes when checked against all elements of the collection.
#an_array_matching	Alias for RSpec::Matchers#match_array.
#an_instance_of	Alias for RSpec::Matchers#be_an_instance_of.
#an_object_eq_to	Alias for RSpec::Matchers#eq.
#an_object_eql_to	Alias for RSpec::Matchers#eql.
#an_object_equal_to	Alias for RSpec::Matchers#equal.
#an_object_existing	Alias for RSpec::Matchers#exist.
#an_object_having_attributes	Alias for RSpec::Matchers#have_attributes.
#an_object_matching	Alias for RSpec::Matchers#match.
#an_object_responding_to	Alias for RSpec::Matchers#respond_to.
#an_object_satisfying	Alias for RSpec::Matchers#satisfy.
#be	Given true, false, or nil, will pass if actual value is true, false or nil (respectively).
#be_a	passes if target.kind_of?(klass).
#be_a_kind_of	Passes if actual.kind_of?(expected).
#be_an	Alias for RSpec::Matchers#be_a.
#be_an_instance_of	Passes if actual.instance_of?(expected).
#be_between	Passes if actual.between?(min, max).
#be_falsey	Passes if actual is falsey (false or nil).
#be_falsy	Alias for RSpec::Matchers#be_falsey.
#be_instance_of	Alias for RSpec::Matchers#be_an_instance_of.
#be_kind_of	Alias for RSpec::Matchers#be_a_kind_of.
#be_nil	Passes if actual is nil.
#be_truthy	Passes if actual is truthy (anything but false or nil).
#be_within	Passes if actual == expected +/- delta.
#change	Applied to a proc, specifies that its execution will cause some value to change.
#changing	Alias for RSpec::Matchers#change.
#contain_exactly	Passes if actual contains all of the expected regardless of order.
#containing_exactly	Alias for RSpec::Matchers#contain_exactly.
#cover	Passes if actual covers expected.
#covering	Alias for RSpec::Matchers#cover.
#end_with	Matches if the actual value ends with the expected value(s).
#ending_with	Alias for RSpec::Matchers#end_with.
#eq	Passes if `actual == expected`.
#eq_to	Alias for RSpec::Matchers#eq.
#eql	Passes if ‘actual.eql?(expected)`.
#eql_to	Alias for RSpec::Matchers#eql.
#equal	Passes if `actual.equal?(expected)` (object identity).
#equal_to	Alias for RSpec::Matchers#equal.
#exist	Passes if `actual.exist?` or `actual.exists?`
#existing	Alias for RSpec::Matchers#exist.
#expect	Supports ‘expect(actual).to matcher` syntax by wrapping #actual in an `ExpectationTarget`.
#have_attributes	Passes if actual’s attribute values match the expected attributes hash.
#having_attributes	Alias for RSpec::Matchers#have_attributes.
#include	Passes if actual includes expected.
#including	Alias for RSpec::Matchers#include.
#match	Given a `Regexp` or `String`, passes if ‘actual.match(pattern)` Given an arbitrary nested data structure (e.g.
#match_array	An alternate form of RSpec::Matchers#contain_exactly that accepts the expected contents as a single array arg rather than splatted out as individual items.
#match_regex	Alias for RSpec::Matchers#match.
#matching	Alias for RSpec::Matchers#match.
#output	With no arg, passes if the block outputs `to_stdout` or `to_stderr`.
#raise_error	With no args, matches if any error is raised.
#raise_exception	Alias for RSpec::Matchers#raise_error.
#raising	Alias for RSpec::Matchers#raise_error.
#respond_to	Matches if the target object responds to all of the names provided.
#respond_to?	:nocov:
#responding_to	Alias for RSpec::Matchers#respond_to.
#satisfy	Passes if the submitted block returns true.
#satisfying	Alias for RSpec::Matchers#satisfy.
#start_with	Matches if the actual value starts with the expected value(s).
#starting_with	Alias for RSpec::Matchers#start_with.
#throw_symbol	Given no argument, matches if a proc throws any Symbol.
#throwing	Alias for RSpec::Matchers#throw_symbol.
#within	Alias for RSpec::Matchers#be_within.
#yield_control	Passes if the method called in the expect block yields, regardless of whether or not arguments are yielded.
#yield_successive_args	Designed for use with methods that repeatedly yield (such as iterators).
#yield_with_args	Given no arguments, matches if the method called in the expect block yields with arguments (regardless of what they are or how many there are).
#yield_with_no_args	Passes if the method called in the expect block yields with no arguments.
#yielding_control	Alias for RSpec::Matchers#yield_control.
#yielding_successive_args	Alias for RSpec::Matchers#yield_successive_args.
#yielding_with_args	Alias for RSpec::Matchers#yield_with_args.
#yielding_with_no_args	Alias for RSpec::Matchers#yield_with_no_args.
#method_missing, #respond_to_missing?

`DefaultImplementations` - Included

#description	The default description.
#chained_method_clause_sentences

`::RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages` - Included

#failure_message	Provides a good generic failure message.
#failure_message_when_negated	Provides a good generic negative failure message.

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) (private)

Takes care of forwarding unhandled messages to the @matcher_execution_context (typically the current running ::RSpec::Core::Example). This is needed by rspec-rails so that it can define matchers that wrap Rails’ test helper methods, but it’s also a useful feature in its own right.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 532


def method_missing(method, *args, &block)
  if @matcher_execution_context.respond_to?(method)
    @matcher_execution_context.__send__ method, *args, &block
  else
    super(method, *args, &block)
  end
end

Instance Attribute Details

#actual (readonly)

Exposes the value being matched against – generally the object object wrapped by RSpec::Matchers#expect.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 449


attr_reader :actual

#block_arg (readonly)

The block parameter used in the expectation

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 456


attr_reader :block_arg

#expected_as_array (readonly)

Returns the expected value as an an array. This exists primarily to aid in upgrading from ::RSpec 2.x, since in ::RSpec 2, #expected always returned an array.

#name (readonly)

The name of the matcher.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 459


attr_reader :name

#rescued_exception (readonly)

Exposes the exception raised during the matching by match_unless_raises. Could be useful to extract details for a failure message.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 453


attr_reader :rescued_exception

Instance Method Details

#actual_arg_for(block) (private)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 522


def actual_arg_for(block)
  block.arity.zero? ? [] : [@actual]
end

#expected

Provides the expected value. This will return an array if multiple arguments were passed to the matcher; otherwise it will return a single value.

#inspect

Adds the name (rather than a cryptic hex number) so we can identify an instance of the matcher in error messages (e.g. for NoMethodError)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 499


def inspect
  "#<#{self.class.name} #{name}>"
end

#respond_to?(method, include_private = false) ⇒ `Boolean`

:nocov: Indicates that this matcher responds to messages from the @matcher_execution_context as well.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 514


def respond_to?(method, include_private=false)
  super || @matcher_execution_context.respond_to?(method, include_private)
end

#respond_to_missing?(method, include_private = false) ⇒ `Boolean`

Indicates that this matcher responds to messages from the @matcher_execution_context as well. Also, supports getting a method object for such methods.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 507


def respond_to_missing?(method, include_private=false)
  super || @matcher_execution_context.respond_to?(method, include_private)
end

Class: RSpec::Matchers::DSL::Matcher

Overview

Constant Summary

::RSpec::Matchers - Included

Class Method Summary

Macros::Deprecated - Extended

Macros - Extended

Instance Attribute Summary

DefaultImplementations - Included

Instance Method Summary

::RSpec::Matchers::Composable - Included

::RSpec::Matchers - Included

DefaultImplementations - Included

::RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages - Included

Dynamic Method Handling

#method_missing(method, *args, &block) (private)

Instance Attribute Details

#actual (readonly)

#block_arg (readonly)

#expected_as_array (readonly)

#name (readonly)

#rescued_exception (readonly)

Instance Method Details

#actual_arg_for(block) (private)

#expected

#inspect

#respond_to?(method, include_private = false) ⇒ Boolean

#respond_to_missing?(method, include_private = false) ⇒ Boolean

`::RSpec::Matchers` - Included

`Macros::Deprecated` - Extended

`Macros` - Extended

`DefaultImplementations` - Included

`::RSpec::Matchers::Composable` - Included

`::RSpec::Matchers` - Included

`DefaultImplementations` - Included

`::RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages` - Included

#respond_to?(method, include_private = false) ⇒ `Boolean`

#respond_to_missing?(method, include_private = false) ⇒ `Boolean`