WillMatchers

Trait that provides a domain specific language (DSL) for expressing assertions in tests using the word will.

For example, if you mix Matchers into a suite class, you can write an equality assertion in that suite like this:

result will equal (3)

Here result is a variable, and can be of any type. If the object is an Int with the value 3, execution will continue (i.e., the expression will result in the unit value, ()). Otherwise, a TestFailedException will be thrown with a detail message that explains the problem, such as "7 did not equal 3". This TestFailedException will cause the test to fail.

Here is a table of contents for this documentation:

• Matchers migration in ScalaTest 2.0
• Checking equality with matchers
• Checking size and length
• Checking strings
• Greater and less than
• Checking Boolean properties with be
• Using custom BeMatchers
• Checking object identity
• Checking an object's class
• Checking numbers against a range
• Checking for emptiness
• Working with "containers"
• Working with "aggregations"
• Working with "sequences"
• Working with "sortables"
• Working with iterators
• Inspector shorthands
• Single-element collections
• Java collections and maps
• Strings and Arrays as collections
• Be as an equality comparison
• Being negative
• Checking that a snippet of code does not compile
• Logical expressions with and and or
• Working with Options
• Checking arbitrary properties with have
• Using length and size with HavePropertyMatchers
• Checking that an expression matches a pattern
• Using custom matchers
• Checking for expected exceptions
• Those pesky parens

Trait MustMatchers is an alternative to Matchers that provides the exact same meaning, syntax, and behavior as Matchers, but uses the verb must instead of should. The two traits differ only in the English semantics of the verb: should is informal, making the code feel like conversation between the writer and the reader; must is more formal, making the code feel more like a written specification.

Checking equality with matchers

ScalaTest matchers provides five different ways to check equality, each designed to address a different need. They are:

result will equal (3) // can customize equality
result will === (3)   // can customize equality and enforce type constraints
result will be (3)    // cannot customize equality, so fastest to compile
result willEqual 3    // can customize equality, no parentheses required
result willBe 3       // cannot customize equality, so fastest to compile, no parentheses required

The “left will equal (right)” syntax requires an org.scalactic.Equality[L] to be provided (either implicitly or explicitly), where L is the left-hand type on which will is invoked. In the "left will equal (right)" case, for example, L is the type of left. Thus if left is type Int, the "left will equal (right)" statement would require an Equality[Int].

By default, an implicit Equality[T] instance is available for any type T, in which equality is implemented by simply invoking == on the left value, passing in the right value, with special treatment for arrays. If either left or right is an array, deep will be invoked on it before comparing with ==. Thus, the following expression will yield false, because Array's equals method compares object identity:

Array(1, 2) == Array(1, 2) // yields false

The next expression will by default not result in a TestFailedException, because default Equality[Array[Int]] compares the two arrays structurally, taking into consideration the equality of the array's contents:

Array(1, 2) will equal (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)

If you ever do want to verify that two arrays are actually the same object (have the same identity), you can use the be theSameInstanceAs syntax, described below.

You can customize the meaning of equality for a type when using "will equal," "will ===," or willEqual syntax by defining implicit Equality instances that will be used instead of default Equality. You might do this to normalize types before comparing them with ==, for instance, or to avoid calling the == method entirely, such as if you want to compare Doubles with a tolerance. For an example, see the main documentation of trait Equality.

You can always supply implicit parameters explicitly, but in the case of implicit parameters of type Equality[T], Scalactic provides a simple "explictly" DSL. For example, here's how you could explicitly supply an Equality[String] instance that normalizes both left and right sides (which must be strings), by transforming them to lowercase:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> import org.scalactic.Explicitly._
import org.scalactic.Explicitly._

scala> import org.scalactic.StringNormalizations._
import org.scalactic.StringNormalizations._

scala> "Hi" will equal ("hi") (after being lowerCased)

The after being lowerCased expression results in an Equality[String], which is then passed explicitly as the second curried parameter to equal. For more information on the explictly DSL, see the main documentation for trait Explicitly.

The "will be" and willBe syntax do not take an Equality[T] and can therefore not be customized. They always use the default approach to equality described above. As a result, "will be" and willBe will likely be the fastest-compiling matcher syntax for equality comparisons, since the compiler need not search for an implicit Equality[T] each time.

The will === syntax (and its complement, will !==) can be used to enforce type constraints at compile-time between the left and right sides of the equality comparison. Here's an example:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> import org.scalactic.TypeCheckedTripleEquals._
import org.scalactic.TypeCheckedTripleEquals._

scala> Some(2) will === (2)
<console>:17: error: types Some[Int] and Int do not adhere to the equality constraint
selected for the === and !== operators; the missing implicit parameter is of
type org.scalactic.CanEqual[Some[Int],Int]
              Some(2) will === (2)
                      ^

By default, the "Some(2) will === (2)" statement would fail at runtime. By mixing in the equality constraints provided by TypeCheckedTripleEquals, however, the statement fails to compile. For more information and examples, see the main documentation for trait TypeCheckedTripleEquals.

Checking size and length

You can check the size or length of any type of object for which it makes sense. Here's how checking for length looks:

result will have length 3

Size is similar:

result will have size 10

The length syntax can be used with String, Array, any scala.collection.GenSeq, any java.util.List, and any type T for which an implicit Length[T] type class is available in scope. Similarly, the size syntax can be used with Array, any scala.collection.GenTraversable, any java.util.Collection, any java.util.Map, and any type T for which an implicit Size[T] type class is available in scope. You can enable the length or size syntax for your own arbitrary types, therefore, by defining Length or Size type classes for those types.

In addition, the length syntax can be used with any object that has a field or method named length or a method named getLength. Similarly, the size syntax can be used with any object that has a field or method named size or a method named getSize. The type of a length or size field, or return type of a method, must be either Int or Long. Any such method must take no parameters. (The Scala compiler will ensure at compile time that the object on which will is being invoked has the appropriate structure.)

Checking strings

You can check for whether a string starts with, ends with, or includes a substring like this:

string will startWith ("Hello")
string will endWith ("world")
string will include ("seven")

You can check for whether a string starts with, ends with, or includes a regular expression, like this:

string will startWith regex "Hel*o"
string will endWith regex "wo.ld"
string will include regex "wo.ld"

And you can check whether a string fully matches a regular expression, like this:

string will fullyMatch regex """(-)?(\d+)(\.\d*)?"""

The regular expression passed following the regex token can be either a String or a scala.util.matching.Regex.

With the startWith, endWith, include, and fullyMatch tokens can also be used with an optional specification of required groups, like this:

"abbccxxx" will startWith regex ("a(b*)(c*)" withGroups ("bb", "cc"))
"xxxabbcc" will endWith regex ("a(b*)(c*)" withGroups ("bb", "cc"))
"xxxabbccxxx" will include regex ("a(b*)(c*)" withGroups ("bb", "cc"))
"abbcc" will fullyMatch regex ("a(b*)(c*)" withGroups ("bb", "cc"))

You can check whether a string is empty with empty:

s willBe empty

You can also use most of ScalaTest's matcher syntax for collections on String by treating the Strings as collections of characters. For examples, see the Strings and Arrays as collections section below.

Greater and less than

You can check whether any type for which an implicit Ordering[T] is available is greater than, less than, greater than or equal, or less than or equal to a value of type T. The syntax is:

one will be < 7
one will be > 0
one will be <= 7
one will be >= 0

Checking Boolean properties with be

If an object has a method that takes no parameters and returns boolean, you can check it by placing a Symbol (after be) that specifies the name of the method (excluding an optional prefix of "is"). A symbol literal in Scala begins with a tick mark and ends at the first non-identifier character. Thus, 'traversableAgain results in a Symbol object at runtime, as does 'completed and 'file. Here's an example:

iter willBe 'traversableAgain

Given this code, ScalaTest will use reflection to look on the object referenced from emptySet for a method that takes no parameters and results in Boolean, with either the name empty or isEmpty. If found, it will invoke that method. If the method returns true, execution will continue. But if it returns false, a TestFailedException will be thrown that will contain a detail message, such as:

non-empty iterator was not traversableAgain

This be syntax can be used with any reference (AnyRef) type. If the object does not have an appropriately named predicate method, you'll get a TestFailedException at runtime with a detailed message that explains the problem. (For the details on how a field or method is selected during this process, see the documentation for BeWord.)

If you think it reads better, you can optionally put a or an after be. For example, java.io.File has two predicate methods, isFile and isDirectory. Thus with a File object named temp, you could write:

temp will be a 'file

Or, given java.awt.event.KeyEvent has a method isActionKey that takes no arguments and returns Boolean, you could assert that a KeyEvent is an action key with:

keyEvent will be an 'actionKey

If you prefer to check Boolean properties in a type-safe manner, you can use a BePropertyMatcher. This would allow you to write expressions such as:

xs willBe traversableAgain
temp will be a file
keyEvent will be an actionKey

These expressions would fail to compile if will is used on an inappropriate type, as determined by the type parameter of the BePropertyMatcher being used. (For example, file in this example would likely be of type BePropertyMatcher[java.io.File]. If used with an appropriate type, such an expression will compile and at run time the Boolean property method or field will be accessed directly; i.e., no reflection will be used. See the documentation for BePropertyMatcher for more information.

Using custom BeMatchers

If you want to create a new way of using be, which doesn't map to an actual property on the type you care about, you can create a BeMatcher. You could use this, for example, to create BeMatcher[Int] called odd, which would match any odd Int, and even, which would match any even Int. Given this pair of BeMatchers, you could check whether an Int was odd or even with expressions like:

num willBe odd
num will not be even

For more information, see the documentation for BeMatcher.

Checking object identity

If you need to check that two references refer to the exact same object, you can write:

ref1 will be theSameInstanceAs ref2

Checking an object's class

If you need to check that an object is an instance of a particular class or trait, you can supply the type to “be a” or “be an”:

result1 willBe a [Tiger]
result1 will not be an [Orangutan]

Because type parameters are erased on the JVM, we recommend you insert an underscore for any type parameters when using this syntax. Both of the following test only that the result is an instance of List[_], because at runtime the type parameter has been erased:

result willBe a [List[_]] // recommended
result willBe a [List[Fruit]] // discouraged

Checking numbers against a range

Often you may want to check whether a number is within a range. You can do that using the +- operator, like this:

sevenDotOh will equal (6.9 +- 0.2)
sevenDotOh will === (6.9 +- 0.2)
sevenDotOh will be (6.9 +- 0.2)
sevenDotOh willEqual 6.9 +- 0.2
sevenDotOh willBe 6.9 +- 0.2

Any of these expressions will cause a TestFailedException to be thrown if the floating point value, sevenDotOh is outside the range 6.7 to 7.1. You can use +- with any type T for which an implicit Numeric[T] exists, such as integral types:

seven will equal (6 +- 2)
seven will === (6 +- 2)
seven will be (6 +- 2)
seven willEqual 6 +- 2
seven willBe 6 +- 2

Checking for emptiness

You can check whether an object is "empty", like this:

traversable willBe empty
javaMap will not be empty

The empty token can be used with any type L for which an implicit Emptiness[L] exists. The Emptiness companion object provides implicits for GenTraversable[E], java.util.Collection[E], java.util.Map[K, V], String, Array[E], and Option[E]. In addition, the Emptiness companion object provides structural implicits for types that declare an isEmpty method that returns a Boolean. Here are some examples:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> List.empty willBe empty

scala> None willBe empty

scala> Some(1) will not be empty

scala> "" willBe empty

scala> new java.util.HashMap[Int, Int] willBe empty

scala> new { def isEmpty = true} willBe empty

scala> Array(1, 2, 3) will not be empty

Working with "containers"

You can check whether a collection contains a particular element like this:

traversable will contain ("five")

The contain syntax shown above can be used with any type C that has a "containing" nature, evidenced by an implicit org.scalatest.enablers.Containing[L], where L is left-hand type on which will is invoked. In the Containing companion object, implicits are provided for types GenTraversable[E], java.util.Collection[E], java.util.Map[K, V], String, Array[E], and Option[E]. Here are some examples:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> List(1, 2, 3) will contain (2)

scala> Map('a' -> 1, 'b' -> 2, 'c' -> 3) will contain ('b' -> 2)

scala> Set(1, 2, 3) will contain (2)

scala> Array(1, 2, 3) will contain (2)

scala> "123" will contain ('2')

scala> Some(2) will contain (2)

ScalaTest's implicit methods that provide the Containing[L] type classes require an Equality[E], where E is an element type. For example, to obtain a Containing[Array[Int]] you must supply an Equality[Int], either implicitly or explicitly. The contain syntax uses this Equality[E] to determine containership. Thus if you want to change how containership is determined for an element type E, place an implicit Equality[E] in scope or use the explicitly DSL. Although the implicit parameter required for the contain syntax is of type Containing[L], implicit conversions are provided in the Containing companion object from Equality[E] to the various types of containers of E. Here's an example:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> List("Hi", "Di", "Ho") will contain ("ho")
org.scalatest.exceptions.TestFailedException: List(Hi, Di, Ho) did not contain element "ho"
        at ...

scala> import org.scalactic.Explicitly._
import org.scalactic.Explicitly._

scala> import org.scalactic.StringNormalizations._
import org.scalactic.StringNormalizations._

scala> (List("Hi", "Di", "Ho") will contain ("ho")) (after being lowerCased)

Note that when you use the explicitly DSL with contain you need to wrap the entire contain expression in parentheses, as shown here.

(List("Hi", "Di", "Ho") will contain ("ho")) (after being lowerCased)
^                                            ^

In addition to determining whether an object contains another object, you can use contain to make other determinations. For example, the contain oneOf syntax ensures that one and only one of the specified elements are contained in the containing object:

List(1, 2, 3, 4, 5) will contain oneOf (5, 7, 9)
Some(7) will contain oneOf (5, 7, 9)
"howdy" will contain oneOf ('a', 'b', 'c', 'd')

Note that if multiple specified elements appear in the containing object, oneOf will fail:

scala> List(1, 2, 3) will contain oneOf (2, 3, 4)
org.scalatest.exceptions.TestFailedException: List(1, 2, 3) did not contain one (and only one) of (2, 3, 4)
        at ...

If you really want to ensure one or more of the specified elements are contained in the containing object, use atLeastOneOf, described below, instead of oneOf. Keep in mind, oneOf means "exactly one of."

Note also that with any contain syntax, you can place custom implicit Equality[E] instances in scope to customize how containership is determined, or use the explicitly DSL. Here's an example:

(Array("Doe", "Ray", "Me") will contain oneOf ("X", "RAY", "BEAM")) (after being lowerCased)

If you have a collection of elements that you'd like to use in a "one of" comparison, you can use "oneElementOf," like this:

List(1, 2, 3, 4, 5) will contain oneElementOf List(5, 7, 9)
Some(7) will contain oneElementOf Vector(5, 7, 9)
"howdy" will contain oneElementOf Set('a', 'b', 'c', 'd')
(Array("Doe", "Ray", "Me") will contain oneElementOf List("X", "RAY", "BEAM")) (after being lowerCased)

The contain noneOf syntax does the opposite of oneOf: it ensures none of the specified elements are contained in the containing object:

List(1, 2, 3, 4, 5) will contain noneOf (7, 8, 9)
Some(0) will contain noneOf (7, 8, 9)
"12345" will contain noneOf ('7', '8', '9')

If you have a collection of elements that you'd like to use in a "none of" comparison, you can use "noElementsOf," like this:

List(1, 2, 3, 4, 5) will contain noElementsOf List(7, 8, 9)
Some(0) will contain noElementsOf Vector(7, 8, 9)
"12345" will contain noElementsOf Set('7', '8', '9')

Working with "aggregations"

As mentioned, the "contain," "contain oneOf," and "contain noneOf" syntax requires a Containing[L] be provided, where L is the left-hand type. Other contain syntax, which will be described in this section, requires an Aggregating[L] be provided, where again L is the left-hand type. (An Aggregating[L] instance defines the "aggregating nature" of a type L.) The reason, essentially, is that contain syntax that makes sense for Option is enabled by Containing[L], whereas syntax that does not make sense for Option is enabled by Aggregating[L]. For example, it doesn't make sense to assert that an Option[Int] contains all of a set of integers, as it could only ever contain one of them. But this does make sense for a type such as List[Int] that can aggregate zero to many integers.

The Aggregating companion object provides implicit instances of Aggregating[L] for types GenTraversable[E], java.util.Collection[E], java.util.Map[K, V], String, Array[E]. Note that these are the same types as are supported with Containing, but with Option[E] missing. Here are some examples:

The contain atLeastOneOf syntax, for example, works for any type L for which an Aggregating[L] exists. It ensures that at least one of (i.e., one or more of) the specified objects are contained in the containing object:

List(1, 2, 3) will contain atLeastOneOf (2, 3, 4)
Array(1, 2, 3) will contain atLeastOneOf (3, 4, 5)
"abc" will contain atLeastOneOf ('c', 'a', 't')

Similar to Containing[L], the implicit methods that provide the Aggregating[L] instances require an Equality[E], where E is an element type. For example, to obtain a Aggregating[Vector[String]] you must supply an Equality[String], either implicitly or explicitly. The contain syntax uses this Equality[E] to determine containership. Thus if you want to change how containership is determined for an element type E, place an implicit Equality[E] in scope or use the explicitly DSL. Although the implicit parameter required for the contain syntax is of type Aggregating[L], implicit conversions are provided in the Aggregating companion object from Equality[E] to the various types of aggregations of E. Here's an example:

(Vector(" A", "B ") will contain atLeastOneOf ("a ", "b", "c")) (after being lowerCased and trimmed)

If you have a collection of elements that you'd like to use in an "at least one of" comparison, you can use "atLeastOneElementOf," like this:

List(1, 2, 3) will contain atLeastOneElementOf List(2, 3, 4)
Array(1, 2, 3) will contain atLeastOneElementOf Vector(3, 4, 5)
"abc" will contain atLeastOneElementOf Set('c', 'a', 't')
(Vector(" A", "B ") will contain atLeastOneElementOf List("a ", "b", "c")) (after being lowerCased and trimmed)

The "contain atMostOneOf" syntax lets you specify a set of objects at most one of which will be contained in the containing object:

List(1, 2, 3, 4, 5) will contain atMostOneOf (5, 6, 7)

If you have a collection of elements that you'd like to use in a "at most one of" comparison, you can use "atMostOneElementOf," like this:

List(1, 2, 3, 4, 5) will contain atMostOneElementOf Vector(5, 6, 7)

The "contain allOf" syntax lets you specify a set of objects that will all be contained in the containing object:

List(1, 2, 3, 4, 5) will contain allOf (2, 3, 5)

If you have a collection of elements that you'd like to use in a "all of" comparison, you can use "allElementsOf," like this:

List(1, 2, 3, 4, 5) will contain allElementsOf Array(2, 3, 5)

The "contain only" syntax lets you assert that the containing object contains only the specified objects, though it may contain more than one of each:

List(1, 2, 3, 2, 1) will contain only (1, 2, 3)

The "contain theSameElementsAs" and "contain theSameElementsInOrderAs syntax differ from the others in that the right hand side is a GenTraversable[_] rather than a varargs of Any. (Note: in a future 2.0 milestone release, possibly 2.0.M6, these will likely be widened to accept any type R for which an Aggregating[R] exists.)

The "contain theSameElementsAs" syntax lets you assert that two aggregations contain the same objects:

List(1, 2, 2, 3, 3, 3) will contain theSameElementsAs Vector(3, 2, 3, 1, 2, 3)

The number of times any family of equal objects appears must also be the same in both the left and right aggregations. The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. For example, if the last 3 element is left out of the right-hand list in the previous example, the expression would fail because the left side has three 3's and the right hand side has only two:

List(1, 2, 2, 3, 3, 3) will contain theSameElementsAs Vector(3, 2, 3, 1, 2)
org.scalatest.exceptions.TestFailedException: List(1, 2, 2, 3, 3, 3) did not contain the same elements as Vector(3, 2, 3, 1, 2)
        at ...

Note that no onlyElementsOf matcher is provided, because it would have the same behavior as theSameElementsAs. (I.e., if you were looking for onlyElementsOf, please use theSameElementsAs instead.)

Working with "sequences"

The rest of the contain syntax, which will be described in this section, requires a Sequencing[L] be provided, where again L is the left-hand type. (A Sequencing[L] instance defines the "sequencing nature" of a type L.) The reason, essentially, is that contain syntax that implies an "order" of elements makes sense only for types that place elements in a sequence. For example, it doesn't make sense to assert that a Map[String, Int] or Set[Int] contains all of a set of integers in a particular order, as these types don't necessarily define an order for their elements. But this does make sense for a type such as Seq[Int] that does define an order for its elements.

The Sequencing companion object provides implicit instances of Sequencing[L] for types GenSeq[E], java.util.List[E], String, and Array[E]. Here are some examples:

Similar to Containing[L], the implicit methods that provide the Aggregating[L] instances require an Equality[E], where E is an element type. For example, to obtain a Aggregating[Vector[String]] you must supply an Equality[String], either implicitly or explicitly. The contain syntax uses this Equality[E] to determine containership. Thus if you want to change how containership is determined for an element type E, place an implicit Equality[E] in scope or use the explicitly DSL. Although the implicit parameter required for the contain syntax is of type Aggregating[L], implicit conversions are provided in the Aggregating companion object from Equality[E] to the various types of aggregations of E. Here's an example:

The "contain inOrderOnly" syntax lets you assert that the containing object contains only the specified objects, in order. The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. Here's an example:

List(1, 2, 2, 3, 3, 3) will contain inOrderOnly (1, 2, 3)

The "contain inOrder" syntax lets you assert that the containing object contains only the specified objects in order, like inOrderOnly, but allows other objects to appear in the left-hand aggregation as well: contain more than one of each:

List(0, 1, 2, 2, 99, 3, 3, 3, 5) will contain inOrder (1, 2, 3)

If you have a collection of elements that you'd like to use in a "in order" comparison, you can use "inOrderElementsOf," like this:

List(0, 1, 2, 2, 99, 3, 3, 3, 5) will contain inOrderElementsOf Array(1, 2, 3)

Note that "order" in inOrder, inOrderOnly, and theSameElementsInOrderAs (described below) in the Aggregation[L] instances built-in to ScalaTest is defined as "iteration order".

Lastly, the "contain theSameElementsInOrderAs" syntax lets you assert that two aggregations contain the same exact elements in the same (iteration) order:

List(1, 2, 3) will contain theSameElementsInOrderAs collection.mutable.TreeSet(3, 2, 1)

The previous assertion succeeds because the iteration order of aTreeSet is the natural ordering of its elements, which in this case is 1, 2, 3. An iterator obtained from the left-hand List will produce the same elements in the same order.

Note that no inOrderOnlyElementsOf matcher is provided, because it would have the same behavior as theSameElementsInOrderAs. (I.e., if you were looking for inOrderOnlyElementsOf, please use theSameElementsInOrderAs instead.)

Working with "sortables"

You can also ask whether the elements of "sortable" objects (such as Arrays, Java Lists, and GenSeqs) are in sorted order, like this:

List(1, 2, 3) willBe sorted

Working with iterators

Althought it seems desireable to provide similar matcher syntax for Scala and Java iterators to that provided for sequences like Seqs, Array, and java.util.List, the ephemeral nature of iterators makes this problematic. Some syntax (such as will contain) is relatively straightforward to support on iterators, but other syntax (such as, for example, Inspector expressions on nested iterators) is not. Rather than allowing inconsistencies between sequences and iterators in the API, we chose to not support any such syntax directly on iterators:

scala> val it = List(1, 2, 3).iterator
it: Iterator[Int] = non-empty iterator

scala> it will contain (2)
<console>:15: error: could not find implicit value for parameter typeClass1: org.scalatest.enablers.Containing[Iterator[Int]]
           it will contain (2)
              ^

Instead, you will need to convert your iterators to a sequence explicitly before using them in matcher expressions:

scala> it.toStream will contain (2)

We recommend you convert (Scala or Java) iterators to Streams, as shown in the previous example, so that you can continue to reap any potential benefits provided by the laziness of the underlying iterator.

Inspector shorthands

You can use the Inspectors syntax with matchers as well as assertions. If you have a multi-dimensional collection, such as a list of lists, using Inspectors is your best option:

val yss =
  List(
    List(1, 2, 3),
    List(1, 2, 3),
    List(1, 2, 3)
  )

forAll (yss) { ys =>
  forAll (ys) { y => y will be > 0 }
}

For assertions on one-dimensional collections, however, matchers provides "inspector shorthands." Instead of writing:

val xs = List(1, 2, 3)
forAll (xs) { x => x will be < 10 }

You can write:

all (xs) will be < 10

The previous statement asserts that all elements of the xs list will be less than 10. All of the inspectors have shorthands in matchers. Here is the full list:

• all - succeeds if the assertion holds true for every element
• atLeast - succeeds if the assertion holds true for at least the specified number of elements
• atMost - succeeds if the assertion holds true for at most the specified number of elements
• between - succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusive
• every - same as all, but lists all failing elements if it fails (whereas all just reports the first failing element)
• exactly - succeeds if the assertion holds true for exactly the specified number of elements

Here are some examples:

scala> import org.scalatest.WillMatchers._
import org.scalatest.WillMatchers._

scala> val xs = List(1, 2, 3, 4, 5)
xs: List[Int] = List(1, 2, 3, 4, 5)

scala> all (xs) will be > 0

scala> atMost (2, xs) will be >= 4

scala> atLeast (3, xs) will be < 5

scala> between (2, 3, xs) will (be > 1 and be < 5)

scala> exactly (2, xs) will be <= 2

scala> every (xs) will be < 10

scala> // And one that fails...

scala> exactly (2, xs) willEqual 2
org.scalatest.exceptions.TestFailedException: 'exactly(2)' inspection failed, because only 1 element
    satisfied the assertion block at index 1:
  at index 0, 1 did not equal 2,
  at index 2, 3 did not equal 2,
  at index 3, 4 did not equal 2,
  at index 4, 5 did not equal 2
in List(1, 2, 3, 4, 5)
        at ...

Like Inspectors, objects used with inspector shorthands can be any type T for which a Collecting[T, E] is availabe, which by default includes GenTraversable, Java Collection, Java Map, Arrays, and Strings. Here are some examples:

scala> import org.scalatest._
import org.scalatest._

scala> import WillMatchers._
import WillMatchers._

scala> all (Array(1, 2, 3)) will be < 5

scala> import collection.JavaConverters._
import collection.JavaConverters._

scala> val js = List(1, 2, 3).asJava
js: java.util.List[Int] = [1, 2, 3]

scala> all (js) will be < 5

scala> val jmap = Map("a" -> 1, "b" -> 2).asJava
jmap: java.util.Map[String,Int] = {a=1, b=2}

scala> atLeast(1, jmap) willBe Entry("b", 2)

scala> atLeast(2, "hello, world!") willBe 'o'

Single-element collections

To assert both that a collection contains just one "lone" element as well as something else about that element, you can use the loneElement syntax provided by trait LoneElement. For example, if a Set[Int] will contain just one element, an Int less than or equal to 10, you could write:

import LoneElement._
set.loneElement will be <= 10

You can invoke loneElement on any type T for which an implicit Collecting[E, T] is available, where E is the element type returned by the loneElement invocation. By default, you can use loneElement on GenTraversable, Java Collection, Java Map, Array, and String.

Java collections and maps

You can use similar syntax on Java collections (java.util.Collection) and maps (java.util.Map). For example, you can check whether a Java Collection or Map is empty, like this:

javaCollection will be ('empty)
javaMap will be ('empty)

Even though Java's List type doesn't actually have a length or getLength method, you can nevertheless check the length of a Java List (java.util.List) like this:

javaList will have length 9

You can check the size of any Java Collection or Map, like this:

javaMap will have size 20
javaSet will have size 90

In addition, you can check whether a Java Collection contains a particular element, like this:

javaCollection will contain ("five")

One difference to note between the syntax supported on Java and Scala collections is that in Java, Map is not a subtype of Collection, and does not actually define an element type. You can ask a Java Map for an "entry set" via the entrySet method, which will return the Map's key/value pairs wrapped in a set of java.util.Map.Entry, but a Map is not actually a collection of Entry. To make Java Maps easier to work with, however, ScalaTest matchers allows you to treat a Java Map as a collection of Entry, and defines a convenience implementation of java.util.Map.Entry in org.scalatest.Entry. Here's how you use it:

javaMap will contain (Entry(2, 3))
javaMap will contain oneOf (Entry(2, 3), Entry(3, 4))

You can you alse just check whether a Java Map contains a particular key, or value, like this:

javaMap will contain key 1
javaMap will contain value "Howdy"

Strings and Arrays as collections

You can also use all the syntax described above for Scala and Java collections on Arrays and Strings. Here are some examples:

scala> import org.scalatest._
import org.scalatest._

scala> import WillMatchers._
import WillMatchers._

scala> atLeast (2, Array(1, 2, 3)) will be > 1

scala> atMost (2, "halloo") willBe 'o'

scala> Array(1, 2, 3) willBe sorted

scala> "abcdefg" willBe sorted

scala> Array(1, 2, 3) will contain atMostOneOf (3, 4, 5)

scala> "abc" will contain atMostOneOf ('c', 'd', 'e')

be as an equality comparison

All uses of be other than those shown previously perform an equality comparison. They work the same as equal when it is used with default equality. This redundancy between be and equals exists in part because it enables syntax that sometimes sounds more natural. For example, instead of writing:

result will equal (null)

You can write:

result will be (null)

(Hopefully you won't write that too much given null is error prone, and Option is usually a better, well, option.) As mentioned previously, the other difference between equal and be is that equal delegates the equality check to an Equality typeclass, whereas be always uses default equality. Here are some other examples of be used for equality comparison:

sum will be (7.0)
boring will be (false)
fun will be (true)
list will be (Nil)
option will be (None)
option will be (Some(1))

As with equal used with default equality, using be on arrays results in deep being called on both arrays prior to calling equal. As a result, the following expression would not throw a TestFailedException:

Array(1, 2) will be (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)

Because be is used in several ways in ScalaTest matcher syntax, just as it is used in many ways in English, one potential point of confusion in the event of a failure is determining whether be was being used as an equality comparison or in some other way, such as a property assertion. To make it more obvious when be is being used for equality, the failure messages generated for those equality checks will include the word equal in them. For example, if this expression fails with a TestFailedException:

option will be (Some(1))

The detail message in that TestFailedException will include the words "equal to" to signify be was in this case being used for equality comparison:

Some(2) was not equal to Some(1)

Being negative

If you wish to check the opposite of some condition, you can simply insert not in the expression. Here are a few examples:

result will not be (null)
sum will not be <= (10)
mylist will not equal (yourList)
string will not startWith ("Hello")

Checking that a snippet of code does not compile

Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest Matchers trait includes the following syntax for that purpose:

"val a: String = 1" willNot compile

If you want to ensure that a snippet of code does not compile because of a type error (as opposed to a syntax error), use:

"val a: String = 1" willNot typeCheck

Note that the willNot typeCheck syntax will only succeed if the given snippet of code does not compile because of a type error. A syntax error will still result on a thrown TestFailedException.

If you want to state that a snippet of code does compile, you can make that more obvious with:

"val a: Int = 1" will compile

Although the previous three constructs are implemented with macros that determine at compile time whether the snippet of code represented by the string does or does not compile, errors are reported as test failures at runtime.

Logical expressions with and and or

You can also combine matcher expressions with and and/or or, however, you must place parentheses or curly braces around the and or or expression. For example, this and-expression would not compile, because the parentheses are missing:

map will contain key ("two") and not contain value (7) // ERROR, parentheses missing!

Instead, you need to write:

map will (contain key ("two") and not contain value (7))

Here are some more examples:

number will (be > (0) and be <= (10))
option will (equal (Some(List(1, 2, 3))) or be (None))
string will (
  equal ("fee") or
  equal ("fie") or
  equal ("foe") or
  equal ("fum")
)

Two differences exist between expressions composed of these and and or operators and the expressions you can write on regular Booleans using its && and || operators. First, expressions with and and or do not short-circuit. The following contrived expression, for example, would print "hello, world!":

"yellow" will (equal ("blue") and equal { println("hello, world!"); "green" })

In other words, the entire and or or expression is always evaluated, so you'll see any side effects of the right-hand side even if evaluating only the left-hand side is enough to determine the ultimate result of the larger expression. Failure messages produced by these expressions will "short-circuit," however, mentioning only the left-hand side if that's enough to determine the result of the entire expression. This "short-circuiting" behavior of failure messages is intended to make it easier and quicker for you to ascertain which part of the expression caused the failure. The failure message for the previous expression, for example, would be:

"yellow" did not equal "blue"

Most likely this lack of short-circuiting would rarely be noticeable, because evaluating the right hand side will usually not involve a side effect. One situation where it might show up, however, is if you attempt to and a null check on a variable with an expression that uses the variable, like this:

map will (not be (null) and contain key ("ouch"))

If map is null, the test will indeed fail, but with a NullArgumentException, not a TestFailedException. Here, the NullArgumentException is the visible right-hand side effect. To get a TestFailedException, you would need to check each assertion separately:

map will not be (null)
map will contain key ("ouch")

If map is null in this case, the null check in the first expression will fail with a TestFailedException, and the second expression will never be executed.

The other difference with Boolean operators is that although && has a higher precedence than ||, and and or have the same precedence. Thus although the Boolean expression (a || b && c) will evaluate the && expression before the || expression, like (a || (b && c)), the following expression:

traversable will (contain (7) or contain (8) and have size (9))

Will evaluate left to right, as:

traversable will ((contain (7) or contain (8)) and have size (9))

If you really want the and part to be evaluated first, you'll need to put in parentheses, like this:

traversable will (contain (7) or (contain (8) and have size (9)))

Working with Options

You can work with options using ScalaTest's equality, empty, defined, and contain syntax. For example, if you wish to check whether an option is None, you can write any of:

option willEqual None
option willBe None
option will === (None)
option willBe empty

If you wish to check an option is defined, and holds a specific value, you can write any of:

option willEqual Some("hi")
option willBe Some("hi")
option will === (Some("hi"))

If you only wish to check that an option is defined, but don't care what it's value is, you can write:

option willBe defined

If you mix in (or import the members of) OptionValues, you can write one statement that indicates you believe an option will be defined and then say something else about its value. Here's an example:

import org.scalatest.OptionValues._
option.value will be < 7

As mentioned previously, you can use also use ScalaTest's contain, contain oneOf, and contain noneOf syntax with options:

Some(2) will contain (2)
Some(7) will contain oneOf (5, 7, 9)
Some(0) will contain noneOf (7, 8, 9)

Checking arbitrary properties with have

Using have, you can check properties of any type, where a property is an attribute of any object that can be retrieved either by a public field, method, or JavaBean-style get or is method, like this:

book will have (
  'title ("Programming in Scala"),
  'author (List("Odersky", "Spoon", "Venners")),
  'pubYear (2008)
)

This expression will use reflection to ensure the title, author, and pubYear properties of object book are equal to the specified values. For example, it will ensure that book has either a public Java field or method named title, or a public method named getTitle, that when invoked (or accessed in the field case) results in a the string "Programming in Scala". If all specified properties exist and have their expected values, respectively, execution will continue. If one or more of the properties either does not exist, or exists but results in an unexpected value, a TestFailedException will be thrown that explains the problem. (For the details on how a field or method is selected during this process, see the documentation for HavePropertyMatcherGenerator.)

When you use this syntax, you must place one or more property values in parentheses after have, seperated by commas, where a property value is a symbol indicating the name of the property followed by the expected value in parentheses. The only exceptions to this rule is the syntax for checking size and length shown previously, which does not require parentheses. If you forget and put parentheses in, however, everything will still work as you'd expect. Thus instead of writing:

array will have length (3)
set will have size (90)

You can alternatively, write:

array will have (length (3))
set will have (size (90))

If a property has a value different from the specified expected value, a TestFailedError will be thrown with a detailed message that explains the problem. For example, if you assert the following on a book whose title is Moby Dick:

book will have ('title ("A Tale of Two Cities"))

You'll get a TestFailedException with this detail message:

The title property had value "Moby Dick", instead of its expected value "A Tale of Two Cities",
on object Book("Moby Dick", "Melville", 1851)

If you prefer to check properties in a type-safe manner, you can use a HavePropertyMatcher. This would allow you to write expressions such as:

book will have (
  title ("Programming in Scala"),
  author (List("Odersky", "Spoon", "Venners")),
  pubYear (2008)
)

These expressions would fail to compile if will is used on an inappropriate type, as determined by the type parameter of the HavePropertyMatcher being used. (For example, title in this example might be of type HavePropertyMatcher[org.publiclibrary.Book]. If used with an appropriate type, such an expression will compile and at run time the property method or field will be accessed directly; i.e., no reflection will be used. See the documentation for HavePropertyMatcher for more information.

Using length and size with HavePropertyMatchers

If you want to use length or size syntax with your own custom HavePropertyMatchers, you can do so, but you must write (of [“the type”]) afterwords. For example, you could write:

book will have (
  title ("A Tale of Two Cities"),
  length (220) (of [Book]),
  author ("Dickens")
)

Prior to ScalaTest 2.0, “length (22)” yielded a HavePropertyMatcher[Any, Int] that used reflection to dynamically look for a length field or getLength method. In ScalaTest 2.0, “length (22)” yields a MatcherFactory1[Any, Length], so it is no longer a HavePropertyMatcher. The (of [<type>]) syntax converts the the MatcherFactory1[Any, Length] to a HavePropertyMatcher[<type>, Int].

Checking that an expression matches a pattern

ScalaTest's Inside trait allows you to make assertions after a pattern match. Here's an example:

case class Name(first: String, middle: String, last: String)

val name = Name("Jane", "Q", "Programmer")

inside(name) { case Name(first, _, _) =>
  first will startWith ("S")
}

You can use inside to just ensure a pattern is matched, without making any further assertions, but a better alternative for that kind of assertion is matchPattern. The matchPattern syntax allows you to express that you expect a value to match a particular pattern, no more and no less:

name will matchPattern { case Name("Sarah", _, _) => }

Using custom matchers

If none of the built-in matcher syntax (or options shown so far for extending the syntax) satisfy a particular need you have, you can create custom Matchers that allow you to place your own syntax directly after will. For example, class java.io.File has a method isHidden, which indicates whether a file of a certain path and name is hidden. Because the isHidden method takes no parameters and returns Boolean, you can call it using be with a symbol or BePropertyMatcher, yielding assertions like:

file will be ('hidden)  // using a symbol
file will be (hidden)   // using a BePropertyMatcher

If it doesn't make sense to have your custom syntax follow be, you might want to create a custom Matcher instead, so your syntax can follow will directly. For example, you might want to be able to check whether a java.io.File's name ends with a particular extension, like this:

// using a plain-old Matcher
file will endWithExtension ("txt")

ScalaTest provides several mechanism to make it easy to create custom matchers, including ways to compose new matchers out of existing ones complete with new error messages. For more information about how to create custom Matchers, please see the documentation for the Matcher trait.

Checking for expected exceptions

Sometimes you need to test whether a method throws an expected exception under certain circumstances, such as when invalid arguments are passed to the method. With Matchers mixed in, you can check for an expected exception like this:

an [IndexOutOfBoundsException] will be thrownBy s.charAt(-1)

If charAt throws an instance of StringIndexOutOfBoundsException, this expression will result in that exception. But if charAt completes normally, or throws a different exception, this expression will complete abruptly with a TestFailedException.

If you need to further isnpect an expected exception, you can capture it using this syntax:

val thrown = the [IndexOutOfBoundsException] thrownBy s.charAt(-1)

This expression returns the caught exception so that you can inspect it further if you wish, for example, to ensure that data contained inside the exception has the expected values. Here's an example:

thrown.getMessage will equal ("String index out of range: -1")

If you prefer you can also capture and inspect an expected exception in one statement, like this:

the [ArithmeticException] thrownBy 1 / 0 will have message "/ by zero"
the [IndexOutOfBoundsException] thrownBy {
  s.charAt(-1)
} will have message "String index out of range: -1"

You can also state that no exception will be thrown by some code, like this:

noException will be thrownBy 0 / 1

Those pesky parens

Perhaps the most tricky part of writing assertions using ScalaTest matchers is remembering when you need or don't need parentheses, but bearing in mind a few simple rules should help. It is also reassuring to know that if you ever leave off a set of parentheses when they are required, your code will not compile. Thus the compiler will help you remember when you need the parens. That said, the rules are:

1. Although you don't always need them, you may choose to always put parentheses around right-hand values, such as the 7 in num will equal (7):

result will equal (4)
array will have length (3)
book will have (
  'title ("Programming in Scala"),
  'author (List("Odersky", "Spoon", "Venners")),
  'pubYear (2008)
)
option will be ('defined)
catMap will (contain key (9) and contain value ("lives"))
keyEvent will be an ('actionKey)
javaSet will have size (90)

2. Except for length, size and message, you must always put parentheses around the list of one or more property values following a have:

file will (exist and have ('name ("temp.txt")))
book will have (
  title ("Programming in Scala"),
  author (List("Odersky", "Spoon", "Venners")),
  pubYear (2008)
)
javaList will have length (9) // parens optional for length and size

3. You must always put parentheses around and and or expressions, as in:

catMap will (contain key (9) and contain value ("lives"))
number will (equal (2) or equal (4) or equal (8))

4. Although you don't always need them, you may choose to always put parentheses around custom Matchers when they appear directly after not:

file will exist
file will not (exist)
file will (exist and have ('name ("temp.txt")))
file will (not (exist) and have ('name ("temp.txt"))
file will (have ('name ("temp.txt") or exist)
file will (have ('name ("temp.txt") or not (exist))

That's it. With a bit of practice it should become natural to you, and the compiler will always be there to tell you if you forget a set of needed parentheses.

Note: ScalaTest's matchers are in part inspired by the matchers of RSpec, Hamcrest, and specs2, and its “willNot compile” syntax by the illTyped macro of shapeless.