123456789_123456789_123456789_123456789_123456789_

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

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 ‘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 ‘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

::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 ‘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 ‘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.


  





    
See Also:

  



  [ GitHub ]


  

  


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



attr_reader :expected_as_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.


  





    
See Also:

  



  [ GitHub ]


  

  


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



def expected
  if expected_as_array.size == 1
    expected_as_array[0]
  else
    expected_as_array
  end
end


  








  

    #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