123456789_123456789_123456789_123456789_123456789_

Module: RSpec::Matchers::DSL

Relationships & Source Files
Namespace Children
Modules:
DefaultImplementations, Macros
Classes:
Matcher
Extension / Inclusion / Inheritance Descendants
Extended In:
::RSpec::Matchers, ::RSpec::Rails::Matchers::RoutingMatchers
Defined in: rspec-expectations/lib/rspec/matchers/dsl.rb

Overview

Defines the custom matcher DSL.

Instance Method Summary

Instance Method Details

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

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:

[ GitHub ] 

  


# File 'rspec-expectations/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


  








  

    #define(name) {|Object| ... } 
    Also known as: #matcher
  



  

    

Defines a custom matcher.


  





  
Parameters:


    
  
  • 
    name
    (Symbol)
—    
    

    the name for the matcher
    

    
  
    • 



Yields:


    
  
  • 
    (Object)
—    
    

    block that is used to define the matcher. The block is evaluated in the context of your custom matcher class. When args are passed to your matcher, they will be yielded here, usually representing the expected value(s).
    

    
  
    • 


  
See Also:

  



  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 73



def define(name, &declarations)
  warn_about_block_args(name, declarations)
  define_method name do |*expected, &block_arg|
    RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
  end
end


  








  

    #define_negated_matcher(negated_name, base_name) {|String| ... } 
  



  

    

Defines a negated matcher. The returned matcher’s ‘description` and failure_message will be overridden to reflect the phrasing of the new name, and the match logic will be based on the original matcher but negated.


  





    

    
Examples:

      
RSpec::Matchers.define_negated_matcher :exclude, :include
include(1, 2).description # => "include 1 and 2"
exclude(1, 2).description # => "exclude 1 and 2"

  


Parameters:


    
  
  • 
    negated_name
    (Symbol)
—    
    

    the name for the negated matcher
    

    
  
    • 
  
  • 
    base_name
    (Symbol)
—    
    

    the name of the original matcher that will be negated
    

    
  
    • 



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:

  



  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 61



def define_negated_matcher(negated_name, base_name, &description_override)
  alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
end


  








  

    #matcher(name, &declarations)  
  



  

    

Alias for #define.


  



  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 79



alias_method :matcher, :define


  








  

    #warn_about_block_args   (private)
  



  

    

:nocov:


  



  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/matchers/dsl.rb', line 94



def warn_about_block_args(name, declarations)
  declarations.parameters.each do |type, arg_name|
    next unless type == :block
    RSpec.warning("Your `#{name}` custom matcher receives a block argument (`#{arg_name}`), " \
                  "but due to limitations in ruby, RSpec cannot provide the block. Instead, " \
                  "use the `block_arg` method to access the block")
  end
end