Defining a custom matcher
rspec-expectations provides a DSL for defining custom matchers. These are often useful for expressing expectations in the domain of your application.
Behind the scenes RSpec::Matchers.define evaluates the define block in the context of a singleton class. If you need to write a more complex matcher and would like to use the Class-approach yourself, please head over to our API-documentation and read the docs about the MatcherProtocol.
Define a matcher with default messages
Given a file named “matcherwithdefaultmessagespec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_a_multiple_of do |expected|
match do |actual|
actual % expected == 0
end
end
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(3) }
end
RSpec.describe 9 do
it { is_expected.not_to be_a_multiple_of(4) }
end
# fail intentionally to generate expected output
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(4) }
end
# fail intentionally to generate expected output
RSpec.describe 9 do
it { is_expected.not_to be_a_multiple_of(3) }
end
When I run rspec ./matcher_with_default_message_spec.rb --format documentation
Then the exit status should not be 0
And the output should contain “is expected to be a multiple of 3”
And the output should contain “is expected not to be a multiple of 4”
And the output should contain “Failure/Error: it { isexpected.to beamultipleof(4) }”
And the output should contain “Failure/Error: it { isexpected.notto beamultiple_of(3) }”
And the output should contain “4 examples, 2 failures”
And the output should contain “expected 9 to be a multiple of 4”
And the output should contain “expected 9 not to be a multiple of 3”.
Overriding the failure_message
Given a file named “matcherwithfailuremessagespec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_a_multiple_of do |expected|
match do |actual|
actual % expected == 0
end
failure_message do |actual|
"expected that #{actual} would be a multiple of #{expected}"
end
end
# fail intentionally to generate expected output
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(4) }
end
When I run rspec ./matcher_with_failure_message_spec.rb
Then the exit status should not be 0
And the stdout should contain “1 example, 1 failure”
And the stdout should contain “expected that 9 would be a multiple of 4”.
Overriding the failuremessagewhen_negated
Given a file named “matcherwithfailureformessage_spec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_a_multiple_of do |expected|
match do |actual|
actual % expected == 0
end
failure_message_when_negated do |actual|
"expected that #{actual} would not be a multiple of #{expected}"
end
end
# fail intentionally to generate expected output
RSpec.describe 9 do
it { is_expected.not_to be_a_multiple_of(3) }
end
When I run rspec ./matcher_with_failure_for_message_spec.rb
Then the exit status should not be 0
And the stdout should contain “1 example, 1 failure”
And the stdout should contain “expected that 9 would not be a multiple of 3”.
Overriding the description
Given a file named “matcheroverridingdescription_spec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_a_multiple_of do |expected|
match do |actual|
actual % expected == 0
end
description do
"be multiple of #{expected}"
end
end
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(3) }
end
RSpec.describe 9 do
it { is_expected.not_to be_a_multiple_of(4) }
end
When I run rspec ./matcher_overriding_description_spec.rb --format documentation
Then the exit status should be 0
And the stdout should contain “2 examples, 0 failures”
And the stdout should contain “is expected to be multiple of 3”
And the stdout should contain “is expected not to be multiple of 4”.
With no args
Given a file named “matcherwithnoargsspec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :have_7_fingers do
match do |thing|
thing.fingers.length == 7
end
end
class Thing
def fingers; (1..7).collect {"finger"}; end
end
RSpec.describe Thing do
it { is_expected.to have_7_fingers }
end
When I run rspec ./matcher_with_no_args_spec.rb --format documentation
Then the exit status should be 0
And the stdout should contain “1 example, 0 failures”
And the stdout should contain “is expected to have 7 fingers”.
With multiple args
Given a file named “matcherwithmultipleargsspec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_the_sum_of do |a,b,c,d|
match do |sum|
a + b + c + d == sum
end
end
RSpec.describe 10 do
it { is_expected.to be_the_sum_of(1,2,3,4) }
end
When I run rspec ./matcher_with_multiple_args_spec.rb --format documentation
Then the exit status should be 0
And the stdout should contain “1 example, 0 failures”
And the stdout should contain “is expected to be the sum of 1, 2, 3, and 4”.
With a block arg
Given a file named “matcherwithblockargspec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :be_lazily_equal_to do
match do |obj|
obj == block_arg.call
end
description { "be lazily equal to #{block_arg.call}" }
end
RSpec.describe 10 do
it { is_expected.to be_lazily_equal_to { 10 } }
end
When I run rspec ./matcher_with_block_arg_spec.rb --format documentation
Then the exit status should be 0
And the stdout should contain “1 example, 0 failures”
And the stdout should contain “is expected to be lazily equal to 10”.
With helper methods
Given a file named “matcherwithinternalhelperspec.rb” with:
require 'rspec/expectations'
RSpec::Matchers.define :have_same_elements_as do |sample|
match do |actual|
similar?(sample, actual)
end
def similar?(a, b)
a.sort == b.sort
end
end
RSpec.describe "these two arrays" do
specify "should be similar" do
expect([1,2,3]).to have_same_elements_as([2,3,1])
end
end
When I run rspec ./matcher_with_internal_helper_spec.rb
Then the exit status should be 0
And the stdout should contain “1 example, 0 failures”.
Scoped in a module
Given a file named “scopedmatcherspec.rb” with:
require 'rspec/expectations'
module MyHelpers
extend RSpec::Matchers::DSL
matcher :be_just_like do |expected|
match {|actual| actual == expected}
end
end
RSpec.describe "group with MyHelpers" do
include MyHelpers
it "has access to the defined matcher" do
expect(5).to be_just_like(5)
end
end
RSpec.describe "group without MyHelpers" do
it "does not have access to the defined matcher" do
expect do
expect(5).to be_just_like(5)
end.to raise_exception
end
end
When I run rspec ./scoped_matcher_spec.rb
Then the stdout should contain “2 examples, 0 failures”.
Scoped in an example group
Given a file named “scopedmatcherspec.rb” with:
require 'rspec/expectations'
RSpec.describe "group with matcher" do
matcher :be_just_like do |expected|
match {|actual| actual == expected}
end
it "has access to the defined matcher" do
expect(5).to be_just_like(5)
end
describe "nested group" do
it "has access to the defined matcher" do
expect(5).to be_just_like(5)
end
end
end
RSpec.describe "group without matcher" do
it "does not have access to the defined matcher" do
expect do
expect(5).to be_just_like(5)
end.to raise_exception
end
end
When I run rspec scoped_matcher_spec.rb
Then the output should contain “3 examples, 0 failures”.
Matcher with separate logic for expect().to and expect().not_to
Given a file named “matcherwithseparateshouldnotlogicspec.rb” with:
RSpec::Matchers.define :contain do |*expected|
match do |actual|
expected.all? { |e| actual.include?(e) }
end
match_when_negated do |actual|
expected.none? { |e| actual.include?(e) }
end
end
RSpec.describe [1, 2, 3] do
it { is_expected.to contain(1, 2) }
it { is_expected.not_to contain(4, 5, 6) }
# deliberate failures
it { is_expected.to contain(1, 4) }
it { is_expected.not_to contain(1, 4) }
end
When I run rspec matcher_with_separate_should_not_logic_spec.rb
Then the output should contain all of these:
| 4 examples, 2 failures |
| expected [1, 2, 3] to contain 1 and 4 |
| expected [1, 2, 3] not to contain 1 and 4 |
Use define_method to create a helper method with access to matcher params
Given a file named “definemethodspec.rb” with:
RSpec::Matchers.define :be_a_multiple_of do |expected|
define_method :is_multiple? do |actual|
actual % expected == 0
end
match { |actual| is_multiple?(actual) }
end
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(3) }
it { is_expected.not_to be_a_multiple_of(4) }
# deliberate failures
it { is_expected.to be_a_multiple_of(2) }
it { is_expected.not_to be_a_multiple_of(3) }
end
When I run rspec define_method_spec.rb
Then the output should contain all of these:
| 4 examples, 2 failures |
| expected 9 to be a multiple of 2 |
| expected 9 not to be a multiple of 3 |
Include a module with helper methods in the matcher
Given a file named “includemodulespec.rb” with:
module MatcherHelpers
def is_multiple?(actual, expected)
actual % expected == 0
end
end
RSpec::Matchers.define :be_a_multiple_of do |expected|
include MatcherHelpers
match { |actual| is_multiple?(actual, expected) }
end
RSpec.describe 9 do
it { is_expected.to be_a_multiple_of(3) }
it { is_expected.not_to be_a_multiple_of(4) }
# deliberate failures
it { is_expected.to be_a_multiple_of(2) }
it { is_expected.not_to be_a_multiple_of(3) }
end
When I run rspec include_module_spec.rb
Then the output should contain all of these:
| 4 examples, 2 failures |
| expected 9 to be a multiple of 2 |
| expected 9 not to be a multiple of 3 |
Using values_match? to compare values and/or compound matchers.
Given a file named “comparevaluesspec.rb” with:
RSpec::Matchers.define :have_content do |expected|
match do |actual|
# The order of arguments is important for `values_match?`, e.g.
# especially if your matcher should handle `Regexp`-objects
# (`/regex/`): First comes the `expected` value, second the `actual`
# one.
values_match? expected, actual
end
end
RSpec.describe 'a' do
it { is_expected.to have_content 'a' }
end
RSpec.describe 'a' do
it { is_expected.to have_content /a/ }
end
RSpec.describe 'a' do
it { is_expected.to have_content a_string_starting_with('a') }
end
When I run rspec ./compare_values_spec.rb --format documentation
Then the exit status should be 0.
Error handling
Make sure your matcher returns either true or false. Take care to handle exceptions appropriately in your matcher, e.g. most cases you might want your matcher to return false if an exception - e.g. ArgumentError - occurs, but there might be edge cases where you want to pass the exception to the user.
You should handle each `StandardError` with care! Do not handle them all in one.
match do |actual|
begin
'[...] Some code'
rescue ArgumentError
false
end
end
Given a file named “errorhandlingspec.rb” with:
class CustomClass; end
RSpec::Matchers.define :is_lower_than do |expected|
match do |actual|
begin
actual < expected
rescue ArgumentError
false
end
end
end
RSpec.describe 1 do
it { is_expected.to is_lower_than 2 }
end
RSpec.describe 1 do
it { is_expected.not_to is_lower_than 'a' }
end
RSpec.describe CustomClass do
it { expect { is_expected.not_to is_lower_than 2 }.to raise_error NoMethodError }
end
When I run rspec ./error_handling_spec.rb --format documentation
Then the exit status should be 0.
Define aliases for your matcher
If you want your matcher to be readable in different contexts, you can use the .alias_matcher-method to provide an alias for your matcher.
Given a file named “alias_spec.rb” with:
RSpec::Matchers.define :be_a_multiple_of do |expected|
match do |actual|
actual % expected == 0
end
end
RSpec::Matchers.alias_matcher :be_n_of , :be_a_multiple_of
RSpec.describe 9 do
it { is_expected.to be_n_of(3) }
end
When I run rspec ./alias_spec.rb --format documentation
Then the exit status should be 0.
With expectation errors that bubble up
By default the match block will swallow expectation errors (e.g. caused by using an expectation such as expect(1).to eq 2), if you wish to allow these to bubble up, pass in the option :notify_expectation_failures => true.
Given a file named “bubblingexpectationerrors_spec.rb” with:
RSpec::Matchers.define :be_a_palindrome do
match(:notify_expectation_failures => true) do |actual|
expect(actual).to be_a(String)
expect(actual.reverse).to eq(actual)
end
end
RSpec.describe "a custom matcher that bubbles up expectation errors" do
it "bubbles expectation errors" do
expect("carriage").to be_a_palindrome
end
end
When I run rspec bubbling_expectation_errors_spec.rb
Then the output should contain all of these:
| Failures: |
| 1) a custom matcher that bubbles up expectation errors bubbles expectation errors |
| Failure/Error: expect(actual.reverse).to eq(actual) |
| expected: “carriage” |
| got: “egairrac” |
| (compared using ==) |
| # ./bubblingexpectationerrors_spec.rb:4 |
| # ./bubblingexpectationerrors_spec.rb:10 |