class RSpec::Matchers::DSL::Matcher

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 {RSpec::Matchers::DSL::Macros Macros} methods available.

Attributes

actual[R]

Exposes the value being matched against – generally the object object wrapped by ‘expect`.

block_arg[R]

The block parameter used in the expectation

expected_as_array[R]

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 expected

name[R]

The name of the matcher.

rescued_exception[R]

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

Public Class Methods

new(name, declarations, matcher_execution_context, *expected, &block_arg) click to toggle source

@api private

# File lib/rspec/matchers/dsl.rb, line 462
def initialize(name, declarations, matcher_execution_context, *expected, &block_arg)
  @name     = name
  @actual   = nil
  @expected_as_array = expected
  @matcher_execution_context = matcher_execution_context
  @chained_method_clauses = []
  @block_arg = block_arg

  klass = class << self
    # See `Macros#define_user_override` above, for an explanation.
    include(@user_method_defs = Module.new)
    self
  end
  RSpec::Support::WithKeywordsWhenNeeded.class_exec(klass, *expected, &declarations)
end

Public Instance Methods

expected() click to toggle source

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 expected_as_array

# File 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() click to toggle source

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

# File lib/rspec/matchers/dsl.rb, line 499
def inspect
  "#<#{self.class.name} #{name}>"
end
respond_to?(method, include_private=false) click to toggle source

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

Calls superclass method RSpec::Matchers#respond_to?
# File 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) click to toggle source

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

Calls superclass method RSpec::Matchers#respond_to_missing?
# File 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

Private Instance Methods

actual_arg_for(block) click to toggle source
# File lib/rspec/matchers/dsl.rb, line 522
def actual_arg_for(block)
  block.arity.zero? ? [] : [@actual]
end
method_missing(method, *args, &block) click to toggle source

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.

Calls superclass method RSpec::Matchers#method_missing
# File 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