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

Do not use. This class is for internal use only.

Relationships & Source Files
Namespace Children
Modules: `DefaultFailureMessages`, `HashFormatting`, `StringEncodingFormatting`
Extension / Inclusion / Inheritance Descendants
Subclasses: RSpec::Matchers::BuiltIn::All, RSpec::Matchers::BuiltIn::Be, RSpec::Matchers::BuiltIn::BeAKindOf, RSpec::Matchers::BuiltIn::BeAnInstanceOf, RSpec::Matchers::BuiltIn::BeBetween, RSpec::Matchers::BuiltIn::BeComparedTo, RSpec::Matchers::BuiltIn::BeFalsey, RSpec::Matchers::BuiltIn::BeNil, RSpec::Matchers::BuiltIn::BePredicate, RSpec::Matchers::BuiltIn::BeTruthy, RSpec::Matchers::BuiltIn::BeWithin, RSpec::Matchers::BuiltIn::Change, RSpec::Matchers::BuiltIn::ChangeFromValue, RSpec::Matchers::BuiltIn::ChangeRelatively, RSpec::Matchers::BuiltIn::ChangeToValue, RSpec::Matchers::BuiltIn::Compound, RSpec::Matchers::BuiltIn::ContainExactly, RSpec::Matchers::BuiltIn::Cover, RSpec::Matchers::BuiltIn::DynamicPredicate, RSpec::Matchers::BuiltIn::EndWith, RSpec::Matchers::BuiltIn::Eq, RSpec::Matchers::BuiltIn::Eql, RSpec::Matchers::BuiltIn::Equal, RSpec::Matchers::BuiltIn::Exist, RSpec::Matchers::BuiltIn::Has, RSpec::Matchers::BuiltIn::HaveAttributes, RSpec::Matchers::BuiltIn::Include, RSpec::Matchers::BuiltIn::Match, RSpec::Matchers::BuiltIn::Output, RSpec::Matchers::BuiltIn::RespondTo, RSpec::Matchers::BuiltIn::Satisfy, RSpec::Matchers::BuiltIn::SpecificValuesChange, RSpec::Matchers::BuiltIn::StartOrEndWith, RSpec::Matchers::BuiltIn::StartWith, RSpec::Matchers::BuiltIn::YieldControl, RSpec::Matchers::BuiltIn::YieldSuccessiveArgs, RSpec::Matchers::BuiltIn::YieldWithArgs, RSpec::Matchers::BuiltIn::YieldWithNoArgs, RSpec::Rails::Matchers::BeValid, Compound::And, Compound::Or, RSpec::Rails::Matchers::ActionCable::HaveBroadcastedTo, RSpec::Rails::Matchers::ActionCable::HaveStream
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `DefaultFailureMessages`, `StringEncodingFormatting`, `HashFormatting`, `::RSpec::Matchers::Composable`
Inherits:	Object
Defined in:	rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb

Overview

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.

Constant Summary

UNDEFINED =

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

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 20
```
Object.new.freeze
```

Class Method Summary

.matcher_name Internal use only
.new(expected = UNDEFINED) ⇒ BaseMatcher constructor Internal use only
.underscore(camel_cased_word) private Internal use only

Borrowed from ActiveSupport.

Instance Attribute Summary

#actual readonly Internal use only
#diffable? ⇒ Boolean readonly Internal use only

::RSpec::Matchers are not diffable by default.
#expected readonly Internal use only
#expects_call_stack_jump? ⇒ Boolean readonly Internal use only
#matcher_name rw Internal use only
#matcher_name=(value) rw Internal use only
#rescued_exception readonly Internal use only
#supports_block_expectations? ⇒ Boolean readonly Internal use only

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.
#supports_value_expectations? ⇒ Boolean readonly Internal use only

`StringEncodingFormatting` - Included

#string_encoding_differs?

Instance Method Summary

#actual_formatted Internal use only
#description ⇒ String Internal use only

Generates a description using ::RSpec::Matchers::EnglishPhrasing.
#expected_formatted Internal use only
#match_unless_raises(*exceptions) Internal use only

Used to wrap a block of code that will indicate failure by raising one of the named exceptions.
#matches?(actual) ⇒ Boolean Internal use only

Indicates if the match is successful.
#assert_ivars(*expected_ivars) private Internal use only
#present_ivars private Internal use only

:nocov:

`DefaultFailureMessages` - Included

#failure_message	Provides a good generic failure message.
#failure_message_when_negated	Provides a good generic negative failure message.

`StringEncodingFormatting` - Included

#format_encoding

Formats a String’s encoding as a human readable string.

`HashFormatting` - Included

#improve_hash_formatting

‘{ :a => 5, :b => 2 }.inspect` produces:

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

Class Method Details

.matcher_name

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 102


def self.matcher_name
  @matcher_name ||= underscore(name.split('::').last)
end

.underscore(camel_cased_word) (private)

Borrowed from ActiveSupport.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 117


def self.underscore(camel_cased_word)
  word = camel_cased_word.to_s.dup
  word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
  word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
  word.tr!('-', '_')
  word.downcase!
  word
end

Instance Attribute Details

#actual (readonly)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 23


attr_reader :actual, :expected, :rescued_exception

#diffable? ⇒ `Boolean` (readonly)

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

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 69


def diffable?
  false
end

#expected (readonly)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 23


attr_reader :actual, :expected, :rescued_exception

#expects_call_stack_jump? ⇒ `Boolean` (readonly)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 87


def expects_call_stack_jump?
  false
end

#matcher_name (rw)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 107


def matcher_name
  if defined?(@matcher_name)
    @matcher_name
  else
    self.class.matcher_name
  end
end

#matcher_name=(value) (rw)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 26


attr_writer :matcher_name

#rescued_exception (readonly)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 23


attr_reader :actual, :expected, :rescued_exception

#supports_block_expectations? ⇒ `Boolean` (readonly)

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.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 77


def supports_block_expectations?
  false
end

#supports_value_expectations? ⇒ `Boolean` (readonly)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 82


def supports_value_expectations?
  true
end

Instance Method Details

#actual_formatted

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 97


def actual_formatted
  RSpec::Support::ObjectFormatter.format(@actual)
end

#assert_ivars(*expected_ivars) (private)

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 129


def assert_ivars(*expected_ivars)
  return unless (expected_ivars - present_ivars).any?
  ivar_list = EnglishPhrasing.list(expected_ivars)
  raise "#{self.class.name} needs to supply#{ivar_list}"
end

#description ⇒ `String`

Generates a description using ::RSpec::Matchers::EnglishPhrasing.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 60


def description
  desc = EnglishPhrasing.split_words(self.class.matcher_name)
  desc << EnglishPhrasing.list(@expected) if defined?(@expected)
  desc
end

#expected_formatted

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 92


def expected_formatted
  RSpec::Support::ObjectFormatter.format(@expected)
end

#match_unless_raises(*exceptions)

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.

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 47


def match_unless_raises(*exceptions)
  exceptions.unshift Exception if exceptions.empty?
  begin
    yield
    true
  rescue *exceptions => @rescued_exception
    false
  end
end

#matches?(actual) ⇒ `Boolean`

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

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 36


def matches?(actual)
  @actual = actual
  match(expected, actual)
end

#present_ivars (private)

:nocov:

[ GitHub ]

# File 'rspec-expectations/lib/rspec/matchers/built_in/base_matcher.rb', line 137


def present_ivars
  instance_variables.map(&:to_sym)
end

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

Overview

Warning:

Constant Summary

Class Method Summary

Instance Attribute Summary

StringEncodingFormatting - Included

Instance Method Summary

DefaultFailureMessages - Included

StringEncodingFormatting - Included

HashFormatting - Included

::RSpec::Matchers::Composable - Included

Class Method Details

.matcher_name

.underscore(camel_cased_word) (private)

Instance Attribute Details

#actual (readonly)

#diffable? ⇒ Boolean (readonly)

#expected (readonly)

#expects_call_stack_jump? ⇒ Boolean (readonly)

#matcher_name (rw)

#matcher_name=(value) (rw)

#rescued_exception (readonly)

#supports_block_expectations? ⇒ Boolean (readonly)

#supports_value_expectations? ⇒ Boolean (readonly)

Instance Method Details

#actual_formatted

#assert_ivars(*expected_ivars) (private)

#description ⇒ String

#expected_formatted

#match_unless_raises(*exceptions)

#matches?(actual) ⇒ Boolean

#present_ivars (private)

`StringEncodingFormatting` - Included

`DefaultFailureMessages` - Included

`StringEncodingFormatting` - Included

`HashFormatting` - Included

`::RSpec::Matchers::Composable` - Included

#diffable? ⇒ `Boolean` (readonly)

#expects_call_stack_jump? ⇒ `Boolean` (readonly)

#supports_block_expectations? ⇒ `Boolean` (readonly)

#supports_value_expectations? ⇒ `Boolean` (readonly)

#description ⇒ `String`

#matches?(actual) ⇒ `Boolean`