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

Creating custom matchers

If none of the built-in matcher syntax satisfies a particular need you have, you can create
custom Matchers that allow
you to place your own syntax directly after should. For example, although you can ensure that a java.io.File has a name
that ends with a particular extension like this:

file.getName should endWith (".txt")

You might prefer
to create a custom Matcher[java.io.File]
named endWithExtension, so you could write expressions like:

file should endWithExtension ("txt")
file should not endWithExtension "txt"
file should (exist and endWithExtension ("txt"))

One good way to organize custom matchers is to place them inside one or more
traits that you can then mix into the suites that need them. Here's an example:

Note: the CustomMatchers companion object exists to make it easy to bring the
matchers 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.

This trait contains one matcher class, FileEndsWithExtensionMatcher, and a def named endWithExtension that returns a new
instance of FileEndsWithExtensionMatcher. Because the class extends Matcher[java.io.File],
the compiler will only allow it be used to match against instances of java.io.File. A matcher must declare an
apply method that takes the type decared in Matcher's type parameter, in this case java.io.File.
The apply method will return a MatchResult whose matches field will indicate whether the match succeeded.
The failureMessage field will provide a programmer-friendly error message indicating, in the event of a match failure, what caused
the match to fail.

The FileEndsWithExtensionMatcher matcher in this example determines success by determining if the passed java.io.File ends with
the desired extension. It does this in the first argument passed to the MatchResult factory method:

name.endsWith(expectedExtension)

In other words, if the file name has the expected extension, this matcher matches.
The next argument to MatchResult's factory method produces the failure message string:

Now you have a Matcher[File] whose apply method first
invokes the converter function to convert the passed File to a String,
then passes the resulting String to endWith. Thus, you could use this version
endWithExtension like the previous one:

scala> new File("output.txt") should endWithExtension("txt")

In addition, by composing twice, you can modify the type of both sides of a match statement
with the same function, like this:

The mapResult method takes a function that accepts a MatchResult and produces a new
MatchResult, which can contain modified arguments and modified error messages. In this example,
the error messages are being modified by wrapping the old arguments in LazyArg
instances that lazily apply the given prettification functions to the toString result of the old args.
Now the error message is clearer:

scala> "7" should beAsIntsGreaterThan ("8")
org.scalatest.exceptions.TestFailedException: "7".toInt was not greater than "8".toInt

Matcher's variance

Matcher is contravariant in its type parameter, T, to make its use more flexible.
As an example, consider the hierarchy:

classFruitclassOrangeextendsFruitclassValenciaOrangeextendsOrange

Given an orange:

val orange = Orange

The expression "orange should" will, via an implicit conversion in ShouldMatchers,
result in an object that has a should
method that takes a Matcher[Orange]. If the static type of the matcher being passed to should is
Matcher[Valencia] it shouldn't (and won't) compile. The reason it shouldn't compile is that
the left value is an Orange, but not necessarily a Valencia, and a
Matcher[Valencia] only knows how to match against a Valencia. The reason
it won't compile is given that Matcher is contravariant in its type parameter, T, a
Matcher[Valencia] is not a subtype of Matcher[Orange].

By contrast, if the static type of the matcher being passed to should is Matcher[Fruit],
it should (and will) compile. The reason it should compile is that given the left value is an Orange,
it is also a Fruit, and a Matcher[Fruit] knows how to match against Fruits.
The reason it will compile is that given that Matcher is contravariant in its type parameter, T, a
Matcher[Fruit] is indeed a subtype of Matcher[Orange].

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:

list should equal (List(1, 2, 3))

The equal (List(1, 2, 3)) expression results in a matcher that holds a reference to the
right value, List(1, 2, 3). The should method invokes apply
on this matcher, passing in list, which is therefore the "left" value. The
matcher will compare the list (the left value) with List(1, 2, 3) (the right
value), and report the result in the returned MatchResult.

Returns a MatcherFactory whose matcher method returns a Matcher,
which has apply method that returns a MatchResult that represents the logical-and
of the results of the wrapped and the passed MatcherFactory applied to the same value.

Returns a MatcherFactory whose matcher method returns a Matcher,
which has apply method that returns a MatchResult that represents the logical-and
of the results of the wrapped and the passed MatcherFactory applied to the same value.

rightMatcherFactory1

the MatcherFactory to logical-and with this MatcherFactory

returns

a MatcherFactory that performs the logical-and of this and the passed MatcherFactory

Returns a matcher whose apply method returns a MatchResult
that represents the logical-and of the results of the wrapped and the passed matcher applied to
the same value.

Returns a matcher whose apply method returns a MatchResult
that represents the logical-and of the results of the wrapped and the passed matcher applied to
the same value.

The reason and has an upper bound on its type parameter is so that the Matcher
resulting from an invocation of and will have the correct type parameter. If you call
and on a Matcher[Orange], passing in a Matcher[Valencia],
the result will have type Matcher[Valencia]. This is correct because both a
Matcher[Orange] and a Matcher[Valencia] know how to match a
Valencia (but a Matcher[Valencia] doesn't know how to
match any old Orange). If you call
and on a Matcher[Orange], passing in a Matcher[Fruit],
the result will have type Matcher[Orange]. This is also correct because both a
Matcher[Orange] and a Matcher[Fruit] know how to match an
Orange (but a Matcher[Orange] doesn't know how to
match any old Fruit).

returns

a matcher that performs the logical-and of this and the passed matcher

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

val beOddAsInt = beOdd compose { (s: String) => s.toInt }

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

final defgetClass(): Class[_]

defhashCode(): Int

final defisInstanceOf[T0]: Boolean

Creates a new Matcher that will produce MatchResults that contain error messages constructed
using arguments that are transformed by the passed prettify function.

Creates a new Matcher that will produce MatchResults that contain error messages constructed
using arguments that are transformed by the passed prettify function. In other words, the MatchResult
produced by this Matcher will use arguments transformed by prettify function to construct the final
error messages.

prettify

a function with which to transform the arguments of error messages.

returns

a new Matcher that will produce MatchResults that contain error messages constructed
using arguments transformed by the passed prettify function.

Creates a new Matcher that will produce MatchResults by applying the original MatchResult
produced by this Matcher to the passed prettify function.

Creates a new Matcher that will produce MatchResults by applying the original MatchResult
produced by this Matcher to the passed prettify function. In other words, the MatchResult
produced by this Matcher will be passed to prettify to produce the final MatchResult

prettify

a function to apply to the original MatchResult produced by this Matcher

returns

a new Matcher that will produce MatchResults by applying the original MatchResult
produced by this Matcher to the passed prettify function

Returns a MatcherFactory whose matcher method returns a Matcher,
which has apply method that returns a MatchResult that represents the logical-or
of the results of the wrapped and the passed MatcherFactory applied to the same value.

Returns a MatcherFactory whose matcher method returns a Matcher,
which has apply method that returns a MatchResult that represents the logical-or
of the results of the wrapped and the passed MatcherFactory applied to the same value.

rightMatcherFactory1

the MatcherFactory to logical-or with this MatcherFactory

returns

a MatcherFactory that performs the logical-or of this and the passed MatcherFactory

Returns a matcher whose apply method returns a MatchResult
that represents the logical-or of the results of this and the passed matcher applied to
the same value.

Returns a matcher whose apply method returns a MatchResult
that represents the logical-or of the results of this and the passed matcher applied to
the same value.

The reason or has an upper bound on its type parameter is so that the Matcher
resulting from an invocation of or will have the correct type parameter. If you call
or on a Matcher[Orange], passing in a Matcher[Valencia],
the result will have type Matcher[Valencia]. This is correct because both a
Matcher[Orange] and a Matcher[Valencia] know how to match a
Valencia (but a Matcher[Valencia] doesn't know how to
match any old Orange). If you call
or on a Matcher[Orange], passing in a Matcher[Fruit],
the result will have type Matcher[Orange]. This is also correct because both a
Matcher[Orange] and a Matcher[Fruit] know how to match an
Orange (but a Matcher[Orange] doesn't know how to
match any old Fruit).