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:
TraversablesThe most common type of matcher is beEqualTo to test the equality of 2 values. 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 must_== 1 |
my favorite! |
1 mustEqual 1 |
if you dislike underscores |
1 should_== 1 |
for should lovers |
1 === 1 |
the ultimate shortcut |
1 must be equalTo(1) |
with a literate style |
There are also other notions of equality
| Matcher | Comment |
|---|---|
beTypedEqualTo |
typed equality. a must beTypedEqualTo(b) will not work if a and b don’t have compatible types |
be_=== |
synonym for beTypedEqualTo |
a ==== b |
synonym for a must beTypedEqualTo(b) |
a must_=== b |
similar to a must_== b but will not typecheck if a and b don’t have the same type |
be_==~ |
check if (a: A) == conv(b: B) when there is an implicit conversion conv from B to 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 |
Note: the beEqualTo matcher is using the regular == Scala equality. However in the case of Arrays, Scala == is just using reference equality, eq. So the beEqualTo matcher has been adapted to use the .deep method on Arrays, transforming them to IndexedSeqs (possibly nested), before checking for equality, so that Array(1, 2, 3) === Array(1, 2, 3) (despite the fact that Array(1, 2, 3) != Array(1, 2, 3)).
Now let’s check 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.size }
// you can use aka to provide some information about the original value, before adaptation
def beShort2 = be_<=(5) ^^ { (t: Any) => t.toString.size aka "the string size" }
// !!! note: use a BeTypedEqualTo matcher when using aka and equality, otherwise you will be matching against Expectable[T] !!!
def beFive = be_===(5) ^^ { (t: Any) => t.toString.size 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 = (be_==(_:Human)) ^^^ ((_:Human).copy(wealth = 0))
// then
Human(age = 20, wealth=1000) must beMostlyEqualTo(Human(age = 20, wealth=1)) // successeventually to try a match a number of times until it succeeds:val iterator = List(1, 2, 3).iterator
// Use eventually(retries, n.millis) to use another 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)attempt to create a matcher that will match on Matcher[scalaz.concurrent.Future[T]] (this requires an execution environment):// see the Matchers-Futures reference card on how to get an ExecutionEnv
implicit val ee: ExecutionEnv = ???
scalaz.concurrent.Future(1) must be_>(0).attempt
scalaz.concurrent.Future { Thread.sleep(100); 1 } must be_>(0).attempt(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'"zip operators to match each value of a tupletype MyTuple = (String, String, String, Seq[(String, Double)])
val t1: MyTuple = ("a", "b", "c", Seq(("d", 1.01), ("e", 2.02)))
val t2: MyTuple = ("a", "b", "c", Seq(("d", 1.00), ("e", 2.00)))
// create a matcher by zipping matchers to the expected value
def beMatching(expected: MyTuple) = expected.zip(startWith, ===, ===, matchSequence)
// match the elements of a sequence with a zipped matcher using string equality for the first field and
// approximate Double equality for the second field
def matchSequence(expected: =>Seq[(String, Double)]) = expected.contain(_.zip(===, ==~)).inOrder
/** type inference doesn't work if this matcher, specialised to Double, is not defined */
def ==~(d: =>Double) = beCloseTo(d +/- 0.1)
t1 must beMatching(t2)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:
// 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 m1: Matcher[String] = { s: String =>
(s.startsWith("hello"), s+" doesn't start with hello")
}
// with a success message and a failure message
def m2: Matcher[String] = { s: String =>
(s.startsWith("hello"), s+" starts with hello", s+" doesn't start with hello")
}
// with a function taking the actual value for the failure message
def m3: Matcher[String] =
((_: String).startsWith("hello"), (_:String)+" doesn't start with hello")
// with 2 functions for the success and failure messages
def m4: Matcher[String] =
((_: String).startsWith("hello"), (s:String) => s+ " starts with hello", (s:String) => s+ " doesn't start with hello")If you want absolute power over matching, you can define your own matcher extending Matcher:
class MyOwn extends Matcher[String] {
def apply[S <: String](s: Expectable[S]) = {
result(s.value.isEmpty,
s.description + " is empty",
s.description + " is not empty",
s)
}
}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, a message when the match is ok, a message when the match is not ok, the “expectable” value. Note that if you change the expectable value you need to use the map method on the s expectable (s.map(other)). This way you preserve the ability of the Expectable to throw an Exception if a subsequent match fails
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 matchersvalue must matcher formAsResult typeclass to go beyond matchersbeA[CaseClass] matcher to automatically create matchers for case classes