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

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

Constant Summary

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

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 Macros

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

Methods included from Composable

#===, #and, #description_of, enumerable?, #or, surface_descriptions_in, #values_match?

Methods included from Pretty

#name, split_words, #to_sentence, #to_word

Methods included from RSpec::Matchers

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, #end_with, #eq, #eql, #equal, #exist, #expect, generated_description, #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 DefaultImplementations

#description, #diffable?, #failure_message, #failure_message_when_negated

Constructor Details

- (Matcher) initialize(name, declarations, matcher_execution_context, *expected)

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



290
291
292
293
294
295
296
297
298
299
300
301
# File 'lib/rspec/matchers/dsl.rb', line 290

def initialize(name, declarations, matcher_execution_context, *expected)
  @name     = name
  @actual   = nil
  @expected_as_array = expected
  @matcher_execution_context = matcher_execution_context

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

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



355
356
357
358
359
360
361
# File 'lib/rspec/matchers/dsl.rb', line 355

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

- (Object) actual (readonly)

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



283
284
285
# File 'lib/rspec/matchers/dsl.rb', line 283

def actual
  @actual
end

- (Object) 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:



319
320
321
# File 'lib/rspec/matchers/dsl.rb', line 319

def expected_as_array
  @expected_as_array
end

- (Object) rescued_exception (readonly)

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



287
288
289
# File 'lib/rspec/matchers/dsl.rb', line 287

def rescued_exception
  @rescued_exception
end

Instance Method Details

- (Object) 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:



307
308
309
310
311
312
313
# File 'lib/rspec/matchers/dsl.rb', line 307

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

- (Object) 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)



324
325
326
# File 'lib/rspec/matchers/dsl.rb', line 324

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

- (Boolean) respond_to?(method, include_private = false)

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

Returns:

  • (Boolean)


338
339
340
# File 'lib/rspec/matchers/dsl.rb', line 338

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

- (Boolean) respond_to_missing?(method, include_private = false)

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)


332
333
334
# File 'lib/rspec/matchers/dsl.rb', line 332

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