Rspec::Matchers::Matchers

An RSpec add on that lets you test your own custom matchers to make sure they generate the correct failure messages and description message.

Why testing custom matchers?

If you are writing a library and plan to ship custom matchers that your library users can use in their specs, then you should be testing your custom matchers as well to make sure that their fail/pass logic is correct and that the messages they output provide meaninful information.

Add this line to your application's Gemfile:

gem 'rspec-matchers-matchers'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rspec-matchers-matchers

The gem defines three custom matchers:

• produce_as_failure_message: used to check the message produced in case of a failed should statement
• produce_as_negative_failure_message used to check the message produced in case of failed should_not statement
• produce_as_description: used to check the message produced when outputting the description of the matcher

In order to use the matchers on your custom matcher, the custom matcher must be instantiated and "primed", or more precisely the messages need to be cached for the produce_as_xxx to test them properly. Assuming you have developed a matcher called be prime to check whether a number is prime

my_number.should be_prime

One of your examples could look like this:

 describe 'be_prime' do

    [...]

   # and then check for the messages
   it 'should generate the correct failure message' do
     # we instantiate the matcher. `be_prime` matcher do not take any block for the expected value, otherwise
     # you could specify it as usual after the matcher name (i.e. be_prime expected_value_block)
     matcher = be_prime
     # in the next line we assign the actual value to the matcher
     cache_messages_for_matcher(matcher, 10)
     # and finally we test that the produced message is what we expect it to be
     matcher.should produce_as_failure_message 'expected 10 to be prime'
   end

 end

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request