Reference card

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

Check all elements

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

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:

class MyFutureSpec extends Specification { def is = s2"""

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

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

"""
  type EE = ExecutionEnv
}

// in a mutable specification
class MyMutableFutureSpec extends mutable.Specification {

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

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

  type EE = ExecutionEnv
}

Time 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