module RSpec::Matchers

RSpec::Matchers provides a number of useful matchers we use to define expectations. Any object that implements the [matcher protocol](Matchers/MatcherProtocol) can be used as a matcher.

## Predicates

In addition to matchers that are defined explicitly, RSpec will create custom matchers on the fly for any arbitrary predicate, giving your specs a much more natural language feel.

A Ruby predicate is a method that ends with a “?” and returns true or false. Common examples are `empty?`, `nil?`, and `instance_of?`.

All you need to do is write `expect(..).to be_` followed by the predicate without the question mark, and RSpec will figure it out from there. For example:

expect([]).to be_empty     # => [].empty?() | passes
expect([]).not_to be_empty # => [].empty?() | fails

In addtion to prefixing the predicate matchers with “be_”, you can also use “be_a_” and “be_an_”, making your specs read much more naturally:

expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes

expect(3).to be_a_kind_of(Integer)          # => 3.kind_of?(Numeric)     | passes
expect(3).to be_a_kind_of(Numeric)          # => 3.kind_of?(Numeric)     | passes
expect(3).to be_an_instance_of(Integer)     # => 3.instance_of?(Integer) | passes
expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails

RSpec will also create custom matchers for predicates like `has_key?`. To use this feature, just state that the object should have_key(:key) and RSpec will call has_key?(:key) on the target. For example:

expect(:a => "A").to have_key(:a)
expect(:a => &