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

Inherits:
Object
  • Object
show all
Extended by:
Macros, RSpec::Matchers::DSL::Macros::Deprecated
Includes:
RSpec::Matchers, Composable, DefaultImplementations
Defined in:
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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Macros

chain, description, diffable, failure_message, failure_message_when_negated, match, match_unless_raises, match_when_negated, supports_block_expectations

Methods included from RSpec::Matchers::DSL::Macros::Deprecated

failure_message_for_should, failure_message_for_should_not, match_for_should, match_for_should_not

Methods included from Composable

#===, #and, #description_of, #or, should_enumerate?, surface_descriptions_in, unreadable_io?, #values_match?

Methods included from RSpec::Matchers

#aggregate_failures, alias_matcher, #all, #be, #be_a, #be_a_kind_of, #be_an_instance_of, #be_between, #be_falsey, #be_nil, #be_truthy, #be_within, #change, clear_generated_description, configuration, #contain_exactly, #cover, define, define_negated_matcher, #end_with, #eq, #eql, #equal, #exist, #expect, generated_description, #have_attributes, #include, #match, #match_array, #output, #raise_error, #respond_to, #satisfy, #start_with, #throw_symbol, #yield_control, #yield_successive_args, #yield_with_args, #yield_with_no_args

Methods included from RSpec::Matchers::DSL

#alias_matcher, #define, #define_negated_matcher

Methods included from DefaultImplementations

#description, #diffable?, #expects_call_stack_jump?, #supports_block_expectations?

Methods included from BuiltIn::BaseMatcher::DefaultFailureMessages

#failure_message, #failure_message_when_negated

Constructor Details

#initialize(name, declarations, matcher_execution_context, *expected, &block_arg) ⇒ Matcher

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Matcher.

457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
 
# File 'lib/rspec/matchers/dsl.rb', line 457
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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object (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.

527
528
529
530
531
532
533
 
# File 'lib/rspec/matchers/dsl.rb', line 527
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 ⇒ Object (readonly)

Exposes the value being matched against -- generally the object object wrapped by expect.

444
445
446
 
# File 'lib/rspec/matchers/dsl.rb', line 444
def actual
  @actual
end

#block_arg ⇒ Object (readonly)

The block parameter used in the expectation

451
452
453
 
# File 'lib/rspec/matchers/dsl.rb', line 451
def block_arg
  @block_arg
end

#expected_as_array ⇒ Object (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:

489
490
491
 
# File 'lib/rspec/matchers/dsl.rb', line 489
def expected_as_array
  @expected_as_array
end

#name ⇒ Object (readonly)

The name of the matcher.

454
455
456
 
# File 'lib/rspec/matchers/dsl.rb', line 454
def name
  @name
end

#rescued_exception ⇒ Object (readonly)

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

448
449
450
 
# File 'lib/rspec/matchers/dsl.rb', line 448
def rescued_exception
  @rescued_exception
end

Instance Method Details

#expected ⇒ Object

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:

477
478
479
480
481
482
483
 
# File 'lib/rspec/matchers/dsl.rb', line 477
def expected
  if expected_as_array.size == 1
    expected_as_array[0]
  else
    expected_as_array
  end
end

#inspect ⇒ Object

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)

494
495
496
 
# File 'lib/rspec/matchers/dsl.rb', line 494
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.

Returns:

  • (Boolean) 
509
510
511
 
# File 'lib/rspec/matchers/dsl.rb', line 509
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.

Returns:

  • (Boolean) 
502
503
504
 
# File 'lib/rspec/matchers/dsl.rb', line 502
def respond_to_missing?(method, include_private=false)
  super || @matcher_execution_context.respond_to?(method, include_private)
end