This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
This class is part of the ScalaTest matchers DSL.
This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers
for an overview of
the matchers DSL.
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
This method enables the following syntax:
This method enables the following syntax:
aMatcher and not (exist) ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and exist ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and not contain value (3)
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and endWith regex (decimalRegex) ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and startWith regex ("1.7")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and include regex ("wor.d")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and fullyMatch regex (decimalRegex) ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and be a ('file)
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and contain key ("one")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher and have size (3 - 1) ^
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.
the MatcherFactory
to logical-and with this MatcherFactory
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
).
a matcher that performs the logical-and of this and the passed matcher
Compose this matcher with the passed function, returning a new matcher.
Compose this matcher with the passed function, returning a new matcher.
This method overrides compose
on Function1
to
return a more specific function type of Matcher
. For example, given
a beOdd
matcher defined like this:
val beOdd = new Matcher[Int] { def apply(left: Int) = MatchResult( left % 2 == 1, left + " was not odd", left + " was odd" ) }
You could use beOdd
like this:
3 should beOdd 4 should not (beOdd)
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:
"3" should beOddAsInt "4" should not (beOddAsInt)
Creates a new Matcher
that will produce MatchResult
s that contain error messages constructed
using arguments that are transformed by the passed prettify
function.
Creates a new Matcher
that will produce MatchResult
s 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.
a function with which to transform the arguments of error messages.
a new Matcher
that will produce MatchResult
s that contain error messages constructed
using arguments transformed by the passed prettify
function.
Creates a new Matcher
that will produce MatchResult
s by applying the original MatchResult
produced by this Matcher
to the passed prettify
function.
Creates a new Matcher
that will produce MatchResult
s 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
a function to apply to the original MatchResult
produced by this Matcher
a new Matcher
that will produce MatchResult
s by applying the original MatchResult
produced by this Matcher
to the passed prettify
function
This method enables the following syntax:
This method enables the following syntax:
aMatcher or not (exist) ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or exist ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or not contain value (3)
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or endWith regex ("7b")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or startWith regex ("1.7")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or include regex ("1.7")
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or fullyMatch regex (decimal) ^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or be a ('directory)
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or contain value (1)
^
This method enables the following syntax:
This method enables the following syntax:
aMatcher or have size (3 - 1) ^
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.
the MatcherFactory
to logical-or with this MatcherFactory
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
).
the matcher to logical-or with this matcher
a matcher that performs the logical-or of this and the passed matcher
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 satisfies a particular need you have, you can create custom
Matcher
s that allow you to place your own syntax directly aftershould
. For example, although you can ensure that ajava.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]
namedendWithExtension
, so you could 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 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 adef
namedendWithExtension
that returns a new instance ofFileEndsWithExtensionMatcher
. 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
FileEndsWithExtensionMatcher
matcher in this example determines success by determining if the passedjava.io.File
ends with the desired extension. It does this in the first argument passed to theMatchResult
factory method: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:s"""File $name did not end with extension "$expectedExtension"""",
For example, consider this matcher expression:
Because the passed
java.io.File
has the nameessay.text
, but the expected extension is"txt"
, the failure message would be:For more information on the fields in a
MatchResult
, including the subsequent field (or fields) that follow the failure message, please see the documentation forMatchResult
.Creating dynamic matchers
There are other ways to create new matchers besides defining one as shown above. For example, you might check that a file is hidden like this:
If you wanted to get rid of the tick mark, you could simply define
hidden
like this:Now you can check that an file is hidden without the tick mark:
You could get rid of the parens with by using
shouldBe
:Creating matchers using logical operators
You can also use ScalaTest matchers' logical operators to combine existing matchers into new ones, like this:
Now you could check that a number is within the tolerance (in this case, between 0 and 10, inclusive), like this:
When defining a full blown matcher, one shorthand is to use one of the factory methods in
Matcher
's companion object. For example, instead of writing this:You could alternately write this:
Either way you define the
beOdd
matcher, you could use it like this:Composing matchers
You can also compose matchers. For example, the
endWithExtension
matcher from the example above can be more easily created by composing a function with the existingendWith
matcher:Now you have a
Matcher[File]
whoseapply
method first invokes the converter function to convert the passedFile
to aString
, then passes the resultingString
toendWith
. Thus, you could use this versionendWithExtension
like the previous one:In addition, by composing twice, you can modify the type of both sides of a match statement with the same function, like this:
At thsi point, however, the error message for the
beAsIntsGreaterThan
gives no hint that theInt
s being compared were parsed fromString
s:To modify error message, you can use trait
MatcherProducers
, which also provides acomposeTwice
method that performs thecompose
...andThen
...compose
operation:Of course, the error messages is still the same:
To modify the error messages, you can use
mapResult
fromMatcherProducers
. Here's an example:The
mapResult
method takes a function that accepts aMatchResult
and produces a newMatchResult
, which can contain modified arguments and modified error messages. In this example, the error messages are being modified by wrapping the old arguments inLazyArg
instances that lazily apply the given prettification functions to thetoString
result of the old args. Now the error message is clearer: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 inMatchers
, 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]
.