The most frequent way to specify some expected behaviour with
For example, if you create a specification for an object manipulating paths:
// describe the functionality
s2"the directoryPath method should return well-formed paths $e1"
// give an example with some code
def e1 = Paths.directoryPath("/tmp/path/to/dir") must beEqualTo("/tmp/path/to/dir/")The must operator takes the actual value returned by directoryPath and applies it to a Matcher built with the expected value. beEqualTo is one of the many matchers defined by
In the following sections you will learn:
The most common type of matcher is beEqualTo to test the equality of 2 values with the underlying == operator where:
the compared types must be the same (as if the language:strictEquality option has been turned on)
the comparison of Arrays uses the .deep method on Arrays, transforming them to IndexedSeqs (possibly nested) Otherwise == on arrays uses the reference equality, so that Array(1, 2, 3) === Array(1, 2, 3), despite the fact that Array(1, 2, 3) != Array(1, 2, 3)
Several syntaxes can be used, according to your own taste
| Matcher | Comment |
|---|---|
1 must beEqualTo(1) |
the normal way |
1 must be_==(1) |
with a symbol |
1 should be_==(1) |
for should lovers |
1 === 1 |
the ultimate shortcut |
There are also other notions of equality:
| Matcher | Comment |
|---|---|
be_==~ |
check if (a: A) === conversion(b: B) when there is an implicit conversion Conversion[B, A] |
beTheSameAs |
reference equality: check if a eq b (a must be(b) also works) |
be |
a must be(b): synonym for beTheSameAs |
beTrue, beFalse |
shortcuts for Boolean equality |
beLike |
partial equality, using a PartialFunction[T, Result]: (1, 2) must beLike { case (1, _) => ok } |
Now let’s check out the other matchers.
These are the all the available matchers when you extend Specification:
Those matchers are optional. To use them, you need to add a new trait to your specification.
Those are additional “data” matchers:
Those matchers can be used to check “content”:
And finally those matchers are Scala / Language related
The easiest way to create a new matcher is to derive it from an existing one. You can:
def beBetween(i: Int, j: Int) = be_>=(i) and be_<=(j)// This matcher adapts the existing `be_<=` matcher to a matcher applicable to `Any`
def beShort1 = be_<=(5) ^^ { (t: Any) => t.toString.length }
// you can use aka to provide some information about the original value, before adaptation
def beShort2 = be_<=(5) ^^ { (t: Any) => t.toString.length aka "the string size" }
// The adaptation can also be done the other way around when it's more readable
def haveExtension(extension: =>String) = ((_: File).getPath) ^^ endWith(extension)Human objects but set their wealth field to 0 so that the equals method will not fail on that field:def beMostlyEqualTo(h: Human) = be_==(h) ^^^ ((_: Human).copy(wealth = 0))
// then
Human(age = 20, wealth = 1000) must beMostlyEqualTo(Human(age = 20, wealth = 1)) // successeventually to try a matcher a number of times until it succeeds:val iterator = List(1, 2, 3).iterator
// Use eventually(retries, n.millis) to specify the number of tries and waiting time
iterator.next must be_==(3).eventuallyawait to create a matcher that will match on Matcher[Future[T]] (this requires an execution environment):Future(1) must be_>(0).await
Future { Thread.sleep(100); 1 } must be_>(0).await(retries = 2, timeout = 100.millis)when or unless to apply a matcher only if a condition is satisfied:1 must be_==(2).when(false) // will return a success
1 must be_==(2).unless(true) // same thing
1 must be_==(2).when(false, "don't check this") // will return a success
1 must be_==(2).unless(true, "don't check this") // same thingiff to say that a matcher must succeed if and only if a condition is satisfied:1 must be_==(1).iff(true) // will return a success
1 must be_==(2).iff(true) // will return a failure
1 must be_==(2).iff(false) // will return a success
1 must be_==(1).iff(false) // will return a failureorSkip to return a Skipped result instead of a Failure if the condition is not satisfied1 must be_==(2).orSkip
1 must be_==(2).orSkip("Precondition failed") // prints "Precondition failed: '1' is not equal to '2'"
1 must be_==(2).orSkip((ko: String) => "BAD " + ko) // prints "BAD '1' is not equal to '2'"orPending to return a Pending result instead of a Failure if the condition is not satisfied1 must be_==(2).orPending
1 must be_==(2).orPending("Precondition failed") // prints "Precondition failed: '1' is not equal to '2'"
1 must be_==(2).orPending((ko: String) => "BAD " + ko) // prints "BAD '1' is not equal to '2'"The easiest way to create a new matcher is to create it from a function returning a tuple with a boolean and one or more messages:
// import the necessary implicit conversions if you are outside of a Specification
// import org.specs2.matcher.Matcher.{given}
// annotate the return type so that implicit conversions can transform your function into a Matcher object
// here just return a boolean and a failure message
def startWithHello: Matcher[String] = { (s: String) =>
(s.startsWith("hello"), s + " doesn't start with hello")
}If you want absolute power over matching, you can define your own matcher extending Matcher:
import org.specs2.execute.Result.*
case class BeMyOwnEmpty() extends Matcher[String] {
def apply[S <: String](s: Expectable[S]) = {
result(s.value.isEmpty, s.description + " is not empty")
}
}
"" must BeMyOwnEmpty()In the code above you have to:
define the apply method (and its somewhat complex signature)
use the protected result method to return a Boolean condition and a failure message
you can use the description method on the Expectable class to return the full description of the expectable including the optional description you setup using the aka method
failure, success, skipped, todo…) instead of matchersAsResult typeclass to go beyond matchers