Trait extended by matcher objects, which may appear after the word be, that can match a value of the specified type.
The value to match is passed to the BeMatcher's apply method. The result is a MatchResult.
A BeMatcher is, therefore, a function from the specified type, T, to a MatchResult.

Although BeMatcher
and Matcher represent very similar concepts, they have no inheritance relationship
because Matcher is intended for use right after should or must
whereas BeMatcher is intended for use right after be.

As an example, you could create BeMatcher[Int]
called odd that would match any odd Int, and one called even that would match
any even Int.
Given this pair of BeMatchers, you could check whether an Int was odd or even with expressions like:

These BeMatchers are defined inside a trait to make them easy to mix into any
suite or spec that needs them.
The CustomMatchers companion object exists to make it easy to bring the
BeMatchers defined in this trait into scope via importing, instead of mixing in the trait. The ability
to import them is useful, for example, when you want to use the matchers defined in a trait in the Scala interpreter console.

The last assertion in the above test will fail with this failure message:

6 was even

For more information on MatchResult and the meaning of its fields, please
see the documentation for MatchResult. To understand why BeMatcher
is contravariant in its type parameter, see the section entitled "Matcher's variance" in the
documentation for Matcher.

Abstract Value Members

Check to see if the specified object, left, matches, and report the result in
the returned MatchResult.

Check to see if the specified object, left, matches, and report the result in
the returned MatchResult. The parameter is named left, because it is
usually the value to the left of a should or must invocation. For example,
in:

num should be (odd)

The be (odd) expression results in a regular Matcher that holds
a reference to odd, the
BeMatcher passed to be. The should method invokes apply
on this matcher, passing in num, which is therefore the "left" value. The
matcher will pass num (the left value) to the BeMatcher's apply
method.

If for some odd reason, you wanted a BeMatcher[String] that
checked whether a string, when converted to an Int,
was odd, you could make one by composing odd with
a function that converts a string to an Int, like this:

val oddAsInt = odd compose { (s: String) => s.toInt }

Now you have a BeMatcher[String] whose apply method first
invokes the converter function to convert the passed string to an Int,
then passes the resulting Int to odd. Thus, you could use
oddAsInt like this: