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
.
the value against which to match
the MatchResult
that represents the result of the match
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 aMatchResult
. A matcher is, therefore, a function from the specified type,T
, to aMatchResult
.Creating custom matchers
If none of the built-in matcher syntax satisfy a particular need you have, you can create custom
Matcher
s that allow you to place your own syntax directly aftershould
ormust
. For example, classjava.io.File
has a methodexists
, which indicates whether a file of a certain path and name exists. Because theexists
method takes no parameters and returnsBoolean
, you can call it usingbe
with a symbol orBePropertyMatcher
, yielding assertions like:Although these expressions will achieve your goal of throwing a
TestFailedException
if the file does not exist, they don't produce the most readable code because the English is either incorrect or awkward. In this case, you might want to create a customMatcher[java.io.File]
namedexist
, which you could then use to write expressions like:One good way to organize custom matchers is to place them inside one or more traits that you can then mix into the suites or specs 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,
FileExistsMatcher
, and aval
namedexist
that refers to an instance ofFileExistsMatcher
. Because the class extendsMatcher[java.io.File]
, the compiler will only allow it be used to match against instances ofjava.io.File
. A matcher must declare anapply
method that takes the type decared inMatcher
's type parameter, in this casejava.io.File
. The apply method will return aMatchResult
whosematches
field will indicate whether the match succeeded. ThefailureMessage
field will provide a programmer-friendly error message indicating, in the event of a match failure, what caused the match to fail.The
FileExistsMatcher
matcher in this example determines success by callingexists
on the passedjava.io.File
. It does this in the first argument passed to theMatchResult
factory method:In other words, if the file exists, this matcher matches. The next argument to
MatchResult
's factory method produces the failure message string:If the passed
java.io.File
is a file (not a directory) and has the nametemp.txt
, for example, the failure message would be:For more information on the fields in a
MatchResult
, including the subsequent three fields that follow the failure message, please see the documentation forMatchResult
.Given the
CustomMatchers
trait as defined above, you can use theexist
syntax in any suite or spec in which you mix in the trait:Note that when you use custom
Matcher
s, you will need to put parentheses around the custom matcher when if followsnot
, as shown in the last assertion above:tempFile should not (exist)
.Matcher's variance
Matcher
is contravariant in its type parameter,T
, to make its use more flexible. As an example, consider the hierarchy:Given an orange:
The expression "
orange should
" will, via an implicit conversion inShouldMatchers
, result in an object that has ashould
method that takes aMatcher[Orange]
. If the static type of the matcher being passed toshould
isMatcher[Valencia]
it shouldn't (and won't) compile. The reason it shouldn't compile is that the left value is anOrange
, but not necessarily aValencia
, and aMatcher[Valencia]
only knows how to match against aValencia
. The reason it won't compile is given thatMatcher
is contravariant in its type parameter,T
, aMatcher[Valencia]
is not a subtype ofMatcher[Orange]
.By contrast, if the static type of the matcher being passed to
should
isMatcher[Fruit]
, it should (and will) compile. The reason it should compile is that given the left value is anOrange
, it is also aFruit
, and aMatcher[Fruit]
knows how to match againstFruit
s. The reason it will compile is that given thatMatcher
is contravariant in its type parameter,T
, aMatcher[Fruit]
is indeed a subtype ofMatcher[Orange]
.