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

- (Object) chain(name, &definition)

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

- (Object) description {|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

- (Object) diffable

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

- (Object) failure_message {|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

- (Object) failure_message_when_negated {|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

- (Object) match {|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

- (Object) match_unless_raises(expected_exception = Exception) {|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("person@company.com")

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

- (Object) match_when_negated {|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

- (Object) supports_block_expectations

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