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 beEmpty
Seq(1, 2, 3) must not(beEmpty)

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

• 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
  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
  .

There are several matchers to check Option and Either instances:

• beSome checks if an element is Some(_)
• beSome(exp) checks if an element is Some(exp)
• beSome(matcher) checks if an element is Some(a) where a satisfies the matcher
• beSome(function: A => AsResult[B]) checks 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) checks if an element is Some(_) and satisfies a function returning a boolean
• beSome.like(partial function) checks if an element is Some(_) and satisfies a partial function returning a Result
• beNone checks if an element is None
• beAsNoneAs checks if 2 values are equal to None at the same time

• beRight checks if an element is Right(_)

• beRight(exp) checks if an element is `Right(exp)
• beRight(matcher) checks if an element is Right(a) where a satisfies the matcher
• beRight(function: A => AsResult[B]) checks 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) checks if an element is Right(_) and satisfies a partial function returning a Result

• beLeft checks if an element is Left(_)

• beLeft(exp) checks if an element is Left(exp)
• beLeft(matcher) checks if an element is Left(a) where a satisfies the matcher
• beLeft(function: A => AsResult[B]) checks 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) checks if an element is Left(_) and satisfies a partial function returning a Result

There are several matchers to check Try instances:

• beSuccessfulTry checks if an element is Success(_)
• beSuccessfulTry.withValue(exp) checks if an element is Success(exp)
• beSuccessfulTry.withValue(matcher) checks if an element is Success(a) where a satisfies the matcher
• beSuccessfulTry.withValue(function: A => AsResult[B]) checks 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) checks if an element is Success(_) and satisfies a function returning a boolean
• beSuccessfulTry.like(partial function) checks if an element is Success(_) and satisfies a partial function returning a Result
• beFailedTry checks if an element is Failure(_)
• beFailedTry.withThrowable[T] checks if an element is Failure(t: T)
• beFailedTry.withThrowable[T](pattern) checks if an element is Failure(t: T) and t.getMessage matches pattern

Testing Futures is quite easy with specs2. You can simply return a value that is Future[R] where R has an AsResult
instance (meaning that R is some kind of result like: Boolean, Result,...).
Then your future will be executed when specs2 executes your example and the result will be collected.

However you will not get the possibility to specify retries or timeouts. For retries and timeouts
you can use the await method on matchers:

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

You can 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[Result] (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)

Execution

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

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

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

  """

// in a mutable specification
class MyMutableFutureSpec(using ee: ExecutionEnv) extends mutable.Specification:
  "Let's check this scala future" >> {
    Future(1) must be_>(0).await
  }

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

• use the execution environment

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

for expressions throwing an exception

• throwA[ExceptionType] checks if a block of code throws an exception of the given type
• throwA[ExceptionType](message = "boom") additionally checks if the exception message is as expected (message is
  being interpreted as a regular expression)
• throwA(exception) or throwAn(exception) checks 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 } checks 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 } checks that the thrown exception satisfies a property

for exception values

• beException[ExceptionType]("message") checks that a Throwable has an expected type and that its message satisfies
  a regular expression

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 checks if a Map has a given key
  Map(1 -> "1") must haveKey(1)

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

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

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

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

• havePairs checks 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 PartialFunctions, so:

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

• beDefinedBy checks 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 } checks if an object is like a given pattern. result can be any expression using a matcher
• beLike { case exp => exp must beXXX } checks if an object is like a given pattern, and verifies a condition
• beNull checks 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) checks if an object is one of a given list
• haveClass checks the class of an object
• haveSuperclass checks if the class of an object as another class as one of its ancestors
• haveInterface checks if an object is implementing a given interface
• beAssignableFrom checks if a class is assignable from another
• beAnInstanceOf[T] checks if an object is an instance of type T

With a typeclass

These matchers can be used with types having a specific typeclass instance: