Class: RSpec::Matchers::BuiltIn::BaseMatcher Private

Inherits:
Object
  • Object
show all
Includes:
Composable, Pretty
Defined in:
lib/rspec/matchers/built_in/base_matcher.rb

Overview

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

Used internally as a base class for matchers that ship with rspec-expectations and rspec-rails.

Warning:

This class is for internal use, and subject to change without notice. We strongly recommend that you do not base your custom matchers on this class. If/when this changes, we will announce it and remove this warning.

Direct Known Subclasses

All, Be, BeAKindOf, BeAnInstanceOf, BeBetween, BeComparedTo, BeFalsey, BeNil, BePredicate, BeTruthy, Compound, ContainExactly, Cover, Eq, Eql, Equal, Exist, Include, Match, Output, StartAndEndWith, YieldControl, YieldWithNoArgs

Constant Summary

UNDEFINED =

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

Used to detect when no arg is passed to initialize. nil cannot be used because it's a valid value to pass.

Object.new.freeze

Instance Method Summary (collapse)

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

Constructor Details

- (BaseMatcher) initialize(expected = UNDEFINED)

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 BaseMatcher

26
27
28
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 26
def initialize(expected=UNDEFINED)
  @expected = expected unless UNDEFINED.equal?(expected)
end

Instance Method Details

- (String) description

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.

Generates a "pretty" description using the logic in Pretty.

Returns:

  • (String) 
78
79
80
81
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 78
def description
  return name_to_sentence unless defined?(@expected)
  "#{name_to_sentence}#{to_sentence @expected}"
end

- (Boolean) diffable?

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.

Matchers are not diffable by default. Override this to make your subclass diffable.

Returns:

  • (Boolean) 
86
87
88
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 86
def diffable?
  false
end

- (String) failure_message

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.

Provides a good generic failure message. Based on description. When subclassing, if you are not satisfied with this failure message you often only need to override description.

Returns:

  • (String) 
60
61
62
63
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 60
def failure_message
  assert_ivars :@actual
  "expected #{@actual.inspect} to #{description}"
end

- (String) failure_message_when_negated

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.

Provides a good generic negative failure message. Based on description. When subclassing, if you are not satisfied with this failure message you often only need to override description.

Returns:

  • (String) 
70
71
72
73
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 70
def failure_message_when_negated
  assert_ivars :@actual
  "expected #{@actual.inspect} not to #{description}"
end

- (Object) match_unless_raises(*exceptions)

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.

Used to wrap a block of code that will indicate failure by raising one of the named exceptions.

This is used by rspec-rails for some of its matchers that wrap rails' assertions.

45
46
47
48
49
50
51
52
53
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 45
def match_unless_raises(*exceptions)
  exceptions.unshift Exception if exceptions.empty?
  begin
    yield
    true
  rescue *exceptions => @rescued_exception
    false
  end
end

- (Boolean) matches?(actual)

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.

Indicates if the match is successful. Delegates to match, which should be defined on a subclass. Takes care of consistently initializing the actual attribute.

Returns:

  • (Boolean) 
34
35
36
37
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 34
def matches?(actual)
  @actual = actual
  match(expected, actual)
end

- (Boolean) supports_block_expectations?

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.

Most matchers are value matchers (i.e. meant to work with expect(value)) rather than block matchers (i.e. meant to work with expect { }), so this defaults to false. Block matchers must override this to return true.

Returns:

  • (Boolean) 
94
95
96
 
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 94
def supports_block_expectations?
  false
end