Method: RSpec::Matchers::DSL#alias_matcher

Defined in:
lib/rspec/matchers/dsl.rb

#alias_matcher(new_name, old_name, options = {}) {|String| ... } ⇒ Object

Defines a matcher alias. The returned matcher's description will be overridden to reflect the phrasing of the new name, which will be used in failure messages when passed as an argument to another matcher in a composed matcher expression.

Examples:

RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
sum_to(3).description # => "sum to 3"
a_list_that_sums_to(3).description # => "a list that sums to 3"
RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
  description.sub("be sorted by", "a list sorted by")
end

be_sorted_by(:age).description # => "be sorted by age"
a_list_sorted_by(:age).description # => "a list sorted by age"

Parameters:

  • new_name (Symbol) —

    the new name for the matcher

  • old_name (Symbol) —

    the original name for the matcher

  • options (Hash) (defaults to: {}) —

    options for the aliased matcher

Options Hash (options):

  • :klass (Class) —

    the ruby class to use as the decorator. (Not normally used).

Yields:

  • (String) —

    optional block that, when given, is used to define the overridden logic. The yielded arg is the original description or failure message. If no block is provided, a default override is used based on the old and new names.

See Also:



32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/rspec/matchers/dsl.rb', line 32

def alias_matcher(new_name, old_name, options={}, &description_override)
  description_override ||= lambda do |old_desc|
    old_desc.gsub(EnglishPhrasing.split_words(old_name), EnglishPhrasing.split_words(new_name))
  end
  klass = options.fetch(:klass) { AliasedMatcher }

  define_method(new_name) do |*args, &block|
    matcher = __send__(old_name, *args, &block)
    matcher.matcher_name = new_name if matcher.respond_to?(:matcher_name=)
    klass.new(matcher, description_override)
  end
  ruby2_keywords new_name if respond_to?(:ruby2_keywords, true)
end