Module: RSpec::Matchers::DSL::Macros

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

Overview

Contains the methods that are available from within the RSpec::Matchers.define DSL for creating custom matchers.

Defined Under Namespace

Modules: Deprecated

Instance Method Summary collapse

Instance Method Details

#chain(name, &definition) ⇒ Object

Convenience for defining methods on this matcher to create a fluent interface. The trick about fluent interfaces is that each method must return self in order to chain methods together. chain handles that for you.

Examples:


RSpec::Matchers.define :have_errors_on do |key|
  chain :with do |message|
    @message = message
  end

  match do |actual|
    actual.errors[key] == @message
  end
end

expect(minor).to have_errors_on(:age).with("Not old enough to participate")


178
179
180
181
182
183
 
# File 'lib/rspec/matchers/dsl.rb', line 178

def chain(name, &definition)
  define_user_override(name, definition) do |*args, &block|
    super(*args, &block)
    self
  end
end

#description {|Object| ... } ⇒ Object

Customize the description to use for one-liners. Only use this when the description generated by default doesn't suit your needs.

Examples:


RSpec::Matchers.define :qualify_for do |expected|
  match { your_match_logic }

  description do
    "qualify for #{expected}"
  end
end

Yields:

  • (Object) —

    actual the actual object (i.e. the value wrapped by expect)



142
143
144
 
# File 'lib/rspec/matchers/dsl.rb', line 142

def description(&definition)
  define_user_override(__method__, definition)
end

#diffable ⇒ Object

Tells the matcher to diff the actual and expected values in the failure message.



148
149
150
 
# File 'lib/rspec/matchers/dsl.rb', line 148

def diffable
  define_method(:diffable?) { true }
end

#failure_message {|Object| ... } ⇒ Object

Customizes the failure messsage to use when this matcher is asked to positively match. Only use this when the message generated by default doesn't suit your needs.

Examples:


RSpec::Matchers.define :have_strength do |expected|
  match { your_match_logic }

  failure_message do |actual|
    "Expected strength of #{expected}, but had #{actual.strength}"
  end
end

Yields:

  • (Object) —

    actual the actual object (i.e. the value wrapped by expect)



105
106
107
 
# File 'lib/rspec/matchers/dsl.rb', line 105

def failure_message(&definition)
  define_user_override(__method__, definition)
end

#failure_message_when_negated {|Object| ... } ⇒ Object

Customize the failure messsage to use when this matcher is asked to negatively match. Only use this when the message generated by default doesn't suit your needs.

Examples:


RSpec::Matchers.define :have_strength do |expected|
  match { your_match_logic }

  failure_message_when_negated do |actual|
    "Expected not to have strength of #{expected}, but did"
  end
end

Yields:

  • (Object) —

    actual the actual object (i.e. the value wrapped by expect)



124
125
126
 
# File 'lib/rspec/matchers/dsl.rb', line 124

def failure_message_when_negated(&definition)
  define_user_override(__method__, definition)
end

#match {|Object| ... } ⇒ Object

Stores the block that is used to determine whether this matcher passes or fails. The block should return a boolean value. When the matcher is passed to expect(...).to and the block returns true, then the expectation passes. Similarly, when the matcher is passed to expect(...).not_to and the block returns false, then the expectation passes.

Examples:


RSpec::Matchers.define :be_even do
  match do |actual|
    actual.even?
  end
end

expect(4).to be_even     # passes
expect(3).not_to be_even # passes
expect(3).to be_even     # fails
expect(4).not_to be_even # fails

Yields:

  • (Object) —

    actual the actual value (i.e. the value wrapped by expect)



39
40
41
42
43
44
45
46
47
48
 
# File 'lib/rspec/matchers/dsl.rb', line 39

def match(&match_block)
  define_user_override(:matches?, match_block) do |actual|
    begin
      @actual = actual
      super(*actual_arg_for(match_block))
    rescue RSpec::Expectations::ExpectationNotMetError
      false
    end
  end
end

#match_unless_raises(expected_exception = Exception) {|Object| ... } ⇒ Object

Use this instead of match when the block will raise an exception rather than returning false to indicate a failure.

Examples:


RSpec::Matchers.define :accept_as_valid do |candidate_address|
  match_unless_raises ValidationException do |validator|
    validator.validate(candidate_address)
  end
end

expect(email_validator).to accept_as_valid("[email protected]")

Yields:

  • (Object) —

    actual the actual object (i.e. the value wrapped by expect)



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/rspec/matchers/dsl.rb', line 77

def match_unless_raises(expected_exception=Exception, &match_block)
  define_user_override(:matches?, match_block) do |actual|
    @actual = actual
    begin
      super(*actual_arg_for(match_block))
    rescue expected_exception => @rescued_exception
      false
    else
      true
    end
  end
end

#match_when_negated {|Object| ... } ⇒ Object

Use this to define the block for a negative expectation (expect(...).not_to) when the positive and negative forms require different handling. This is rarely necessary, but can be helpful, for example, when specifying asynchronous processes that require different timeouts.

Yields:

  • (Object) —

    actual the actual value (i.e. the value wrapped by expect)



56
57
58
59
60
61
 
# File 'lib/rspec/matchers/dsl.rb', line 56

def match_when_negated(&match_block)
  define_user_override(:does_not_match?, match_block) do |actual|
    @actual = actual
    super(*actual_arg_for(match_block))
  end
end

#supports_block_expectations ⇒ Object

Declares that the matcher can be used in a block expectation. Users will not be able to use your matcher in a block expectation without declaring this. (e.g. expect { do_something }.to matcher).



156
157
158
 
# File 'lib/rspec/matchers/dsl.rb', line 156

def supports_block_expectations
  define_method(:supports_block_expectations?) { true }
end