Matchers

Traversables can be checked with several matchers. If you want to check the size of a Traversable

• check if it is empty
    Seq() must be empty
  Seq(1, 2, 3) must not be empty

• check its size
    Seq(1, 2) must have size(2)
  Seq(1, 2) must have length(2) // equivalent to size
    Seq(1, 2) must have size(be_>=(1)) // with a matcher

note: you might have to annotate the haveSize matcher when using some combinators. For example: (futures: Future[Seq[Int]]) must haveSize[Seq[Int]](1).await

• check its ordering (works with any type T which has an Ordering)
    Seq(1, 2, 3) must beSorted

Check each element individually

Then you can check the elements which are contained in the Traversable

• if a simple value is contained
    Seq(1, 2, 3) must contain(2)

• if a value matching a specific matcher is contained
    Seq(1, 2, 3) must contain(be_>=(2))

• if a value passing a function returning a Result is contained (MatchResult, ScalaCheck Prop,...)
    Seq(1, 2, 3) must contain((i: Int) => i must be_>=(2))

• note that a Seq[A] is also a function Int => A so if you want to check that a sequence is contained in another you need to use a matcher
    Seq(Seq(1)) must contain(===(Seq(1)))

• there are also 2 specialized matchers to check the string representation of the elements
    Seq(1234, 6237) must containMatch("23") // matches with ".*23.*"
  Seq(1234, 6234) must containPattern(".*234") // matches with !.*234"

For each of the check above you can indicate how many times the check should be satisfied:

• Seq(1, 2, 3) must contain(be_>(0)).forall // this will stop after the first failure
• Seq(1, 2, 3) must contain(be_>(0)).foreach // this will report all failures
• Seq(1, 2, 3) must contain(be_>(0)).atLeastOnce
• Seq(1, 2, 3) must contain(be_>(2)).atMostOnce
• Seq(1, 2, 3) must contain(be_>(2)).exactly(1.times)
• Seq(1, 2, 3) must contain(be_>(2)).exactly(1)
• Seq(1, 2, 3) must contain(be_>(1)).between(1.times, 2.times)
• Seq(1, 2, 3) must contain(be_>(1)).between(1, 2)

Check all elements

The other types of checks involve comparing the Traversable elements to other elements (values, matchers, function returning a Result)

• with a set of values
    Seq(1, 2, 3, 4) must contain(2, 4)
    which is the same thing as
    Seq(1, 2, 3, 4) must contain(allOf(2, 4))

• with a set of matchers
    Seq(1, 2, 3, 4) must contain(allOf(be_>(0), be_>(1)))

• checking that the order is satisfied
    Seq(1, 2, 3, 4) must contain(allOf(be_>(0), be_>(1)).inOrder)

Note that allOf tries to make each check be successful at least once, even if it is on the same value. On the other hand, if you want to specify that each check must succeed on a different value you should use onDistinctValues. For example this will fail:
Seq(1) must contain(allOf(1, 1)).onDistinctValues

The eachOf method does the same thing (and this example will fail as well):
Seq(1) must contain(eachOf(1, 1))

Another frequent use of Traversable matchers is to check if the Traversable have the right number of elements. For this you can use:

• atLeast, which is actually another name for allOf, where the traversable can contain more elements than required
    Seq(1, 2, 3, 4) must contain(atLeast(2, 4))

• atMost where the traversable can not contain more elements than required
    Seq(2, 3) must contain(atMost(2, 3, 4))

• exactly where the traversable must contain exactly the specified number of elements
    Seq(1, 2) must contain(exactly(2, 1))

The atLeast/atMost/exactly operators work on distinct values by default (because this is easier for counting the correspondence between actual values and expected ones). However you can use onDistinctValues(false) if you don't care.

Finally, if you want to get the differences between 2 traversables:

Seq(2, 4, 1) must containTheSameElementsAs(Seq(1, 4, 2))

Numerical values can be compared with the following matchers

• beLessThanOrEqualTo compares any Ordered type with <=
    1 must be_<=(2)
    1 must beLessThanOrEqualTo(2)

• beLessThan compares any Ordered type with <
    1 must be_<(2)
    1 must beLessThan(2)

• beGreaterThanOrEqualTo compares any Ordered type with >=
    2 must be_>=(1)
    2 must beGreaterThanOrEqualTo(1)

• beGreaterThan compares any Ordered type with >
    2 must be_>(1)
    2 must beGreaterThan(1)

• beCloseTo check if 2 Numerics are close to each other
      1.0 must beCloseTo(1, 0.5)
    4 must be ~(5 +/- 2)
    4.994 must beCloseTo(5.0 within 2.significantFigures)

• beBetween check if a value is between 2 others
      5 must beBetween(3, 6)
    5 must beBetween(3, 6).excludingEnd
    5 must beBetween(4, 6).excludingStart
    5 must beBetween(4, 6).excludingBounds
    // with brackets notation
      5 must (be[(4, 7)])
      5 must (be[(4, 6)[)
                                                                                                                 .

There are several matchers to check Option and Either instances:

• beSome check if an element is Some(_)
• beSome(exp) check if an element is Some(exp)
• beSome(matcher) check if an element is Some(a) where a satisfies the matcher
• beSome(function: A => AsResult[B]) check if an element is Some(a) where function(a) returns a successful Result
  (note that a Seq[A] is also a function Int => A so if you want to check that a sequence is contained in Some you need to use a matcher: beSome(===(Seq(1)))
• beSome.which(function) check if an element is Some(_) and satisfies a function returning a boolean
• beSome.like(partial function) check if an element is Some(_) and satisfies a partial function returning a MatchResult
• beNone check if an element is None
• beAsNoneAs check if 2 values are equal to None at the same time

• beRight check if an element is Right(_)

• beRight(exp) check if an element is `Right(exp)
• beRight(matcher) check if an element is Right(a) where a satisfies the matcher
• beRight(function: A => AsResult[B]) check if an element is Right(a) where function(a) returns a successful Result
  (note that a Seq[A] is also a function Int => A so if you want to check that a sequence is contained in Right you need to use a matcher: beRight(===(Seq(1)))
• beRight.like(partial function) check if an element is Right(_) and satisfies a partial function returning a MatchResult

• beLeft check if an element is Left(_)

• beLeft(exp) check if an element is Left(exp)
• beLeft(matcher) check if an element is Left(a) where a satisfies the matcher
• beLeft(function: A => AsResult[B]) check if an element is Left(a) where function(a) returns a successful Result
  (note that a Seq[A] is also a function Int => A so if you want to check that a sequence is contained in Left you need to use a matcher: beLeft(===(Seq(1)))
• beLeft.like(partial function) check if an element is Left(_) and satisfies a partial function returning a MatchResult

There are several matchers to check Try instances:

• beSuccessfulTry check if an element is Success(_)
• beSuccessfulTry.withValue(exp) check if an element is Success(_)
• beSuccessfulTry.withValue(matcher) check if an element is Success(a) where a satisfies the matcher
• beSuccessfulTry.withValue(function: A => AsResult[B]) check if an element is Success(a) where function(a) returns a successful Result
  (note that a Seq[A] is also a function Int => A so if you want to check that a sequence is contained in Success you need to use a matcher: beSuccessfulTry.withValue(===(Seq(1)))
• beSuccessfulTry.which(function) check if an element is Success(_) and satisfies a function returning a boolean
• beSuccessfulTry.like(partial function) check if an element is Success(_) and satisfies a partial function returning a MatchResult
• beFailedTry check if an element is Failure(_)
• beFailedTry.withThrowable[T] check if an element is Failure(t: T)
• beFailedTry.withThrowable[T](pattern) check if an element is Failure(t: T) and t.getMessage matches pattern

Testing Futures is quite easy with specs2. You can transform any Matcher[T] into a Matcher[Future[T] with the await method

Future(1) must be_>(0).await

You can also specify a timeout value and a number of retries

Future { Thread.sleep(100); 1 } must be_>(0).await(retries = 2, timeout = 100.millis)

// only retries, timeout is 1.second
Future { Thread.sleep(100); 1 } must be_>(0).retryAwait(retries = 2)

// only timeout, retries = 0
Future { Thread.sleep(100); 1 } must be_>(0).awaitFor(100.millis)

Another possibility is for you to obtain a Future[MatchResult[T]] (or any Future[R] where R has an AsResult typeclass instance). In that case you can use await directly on the Future to get a Result

Future(1 === 1).await
Future(1 === 1).await(retries = 2, timeout = 100.millis)

Scalaz Futures

All of the above is applicable to scalaz.concurrent.Future by using the method attempt instead of await.

Execution

The await/attempt methods require an implicit org.specs2.concurrent.ExecutionEnv (see here for more details). You can pass one in the body of your examples:

import org.specs2.matcher.FuturezMatchers._

class MyFutureSpec(implicit ee: ExecutionEnv) extends Specification { def is = s2"""

 Let's check this scala future ${
   Future(1) must be_>(0).await
 }

 Let's check this scalaz future ${
   scalaz.concurrent.Future(1) must be_>(0).attempt
 }

"""
}

// in a mutable specification
class MyMutableFutureSpec(implicit ee: ExecutionEnv) extends mutable.Specification {

  "Let's check this scala future" >> {
    Future(1) must be_>(0).await
  }

  "Let's check this scalaz future" >> {
    scalaz.concurrent.Future(1) must be_>(0).attempt
  }

}

Time factor

Some actions can be a lot slower when executed on a continuous integration server rather than a developer machine and some timeouts will fail.
You can avoid this by setting the timeFactor argument which will multiply the durations used when awaiting / attempting by a constant factor.

sbt> testOnly *MyFuturesSpec* -- timeFactor 3

specs2 offers very compact ways of checking that some exceptions are thrown:

• throwA[ExceptionType] check if a block of code throws an exception of the given type
• throwA[ExceptionType](message = "boom") additionally check if the exception message is as expected (message is
  being interpreted as a regular expression)
• throwA(exception) or throwAn(exception) check if a block of code throws an exception of the same type, with the
    same message
• throwA[ExceptionType].like { case e => e must matchSomething } or
    throwA(exception).like { case e => e must matchSomething } check that the thrown exception satisfies a property
• throwA[ExceptionType](me.like { case e => e must matchSomething } or
    throwA(exception).like { case e => e must matchSomething } check that the thrown exception satisfies a property

For all the above matchers you can use throwAn instead of throwA if the exception name starts with a vowel for better
readability.

Maps have their own matchers as well, to check keys and values:

• haveKey check if a Map has a given key
      Map(1 -> "1") must haveKey(1)

• haveKeys check if a Map has several keys
      Map(1 -> "1", 2 -> "2") must haveKeys(1, 2)

• haveValue check if a Map has a given value
      Map(1 -> "1") must haveValue("1")

• haveValues check if a Map has several values
      Map(1 -> "1", 2 -> "2") must haveValues("1", "2")

• havePair check if a Map has a given pair of values
      Map(1 -> "1") must havePair(1 -> "1")

• havePairs check if a Map has some pairs of values
      Map(1->"1", 2->"2", 3->"3") must havePairs(1->"1", 2->"2")

But Maps are also Partial Functions, so:

• beDefinedAt check if a PartialFunction is defined for a given value
      partial must beDefinedAt(1)

• beDefinedBy check if a PartialFunction is defined for a given value
    and returns another one
      partial must beDefinedBy(1 -> true)

These matchers can be used with any object, regardless of its type:

• beLike { case exp => result } check if an object is like a given pattern. result can be any expression using a matcher
• beLike { case exp => exp must beXXX } check if an object is like a given pattern, and verifies a condition
• beNull check if an object is null
• beAsNullAs when 2 objects must be null at the same time if one of them is null
• beOneOf(a, b, c) check if an object is one of a given list
• haveClass check the class of an object
• haveSuperclass check if the class of an object as another class as one of its ancestors
• haveInterface check if an object is implementing a given interface
• beAssignableFrom check if a class is assignable from another
• beAnInstanceOf[T] check if an object is an instance of type T