Home / Learn / 14 Testing
14.2 Testing failures: expect fails
Page 3 of 10
14.2.1 What a failure path is
A function that can fail (section 7.2) declares how, with fails and a kind of errors, and fails with fail and one of the kind's variants. Each way a function can end, by returning or by failing with a given variant, is a path through it. The return is the happy path; each variant it can fail with is a failure path.
A failure path is behavior, as much as a returned value is. A coupon code that does not exist must be refused, and saying so is part of what the function is for. The order intake of section 7.8 already tested its failure paths with expect fails, with a short explanation. This section covers it in full.
14.2.2 Why every failure path needs an example
Here is a coupon function where an unknown code takes nothing off, instead of failing, and its one example:
module coupons
--- The percent that a coupon code takes off. An unknown code takes nothing off.
pub percent_off(code: Text) -> Int = if code == "SPRING10" then 10 else if code == "VIP25" then 25 else 0
--- The price of a cart after a coupon, in cents.
pub apply_coupon(code: Text, cents: Int) -> Int = cents - cents * percent_off(code) / 100
pub main() -> Unit
uses @console: Console[print]
=
let spring = apply_coupon("SPRING10", cents: 5000)
let winter = apply_coupon("WINTER5", cents: 5000)
@console.print("SPRING10: {spring}, WINTER5: {winter}")
example "SPRING10 takes 10 percent off"
do apply_coupon("SPRING10", cents: 5000)
expect result == 4500una run . prints:
SPRING10: 4500, WINTER5: 5000$ una test .
example coupons "SPRING10 takes 10 percent off" ... ok
1 example: 1 passed, 0 failedEvery check passes. Yet a customer who mistypes SPRING10 pays full price and is never told why. The example tests the one path someone thought of. What the store wanted, that an unknown code is refused, is written nowhere, so nothing can fail when the code does not do it. An example for each failure path is how you write it down.
14.2.3 How to write expect fails
expect fails and the name of a variant:
expect fails Unknownholds when thedoline failed with the variantUnknown.- Name the variant only, without its fields:
expect fails Unknown, notexpect fails Unknown("WINTER5"). - The variant is of the
docall's error kind, the kind itsfailsclause names. - The
doline needs no handling clause. Whatever it fails with, the example catches it, andexpect failsnames the variant. A handling clause such asif error useunder adoline is a syntax error, U0101. When you want the failure as a value instead,do attempt f(…)gives aResult(section 7.4), whichexpect result is Errcan test. A failure as a value shows both.
14.2.4 The failure paths of a coupon
This step applies a coupon code to a cart. A code can be unknown, and a coupon needs a cart of at least 20.00:
module coupons
--- Why a coupon was not accepted.
pub kind CouponError = Unknown(code: Text) | BelowMinimum(minimum: Int)
--- The percent that a coupon code takes off.
pub percent_off(code: Text) -> Int
fails CouponError
=
if code == "SPRING10" then 10 else if code == "VIP25" then 25 else fail Unknown(code)
--- The price of a cart after a coupon, in cents. A coupon needs a cart of at least 20.00.
pub apply_coupon(code: Text, cents: Int) -> Int
fails CouponError
=
let percent = percent_off(code)
if error pass
if cents < 2000
fail BelowMinimum(minimum: 2000)
else
cents - cents * percent / 100
pub main() -> Unit
uses @console: Console[print]
=
let spring = attempt apply_coupon("SPRING10", cents: 5000)
let winter = attempt apply_coupon("WINTER5", cents: 5000)
@console.print("{spring} {winter}")
example "SPRING10 takes 10 percent off"
do apply_coupon("SPRING10", cents: 5000)
expect result == 4500
example "an unknown code is Unknown"
do apply_coupon("WINTER5", cents: 5000)
expect fails Unknown
example "a small cart is BelowMinimum, even with a good code"
do apply_coupon("VIP25", cents: 1500)
expect fails BelowMinimum
example "the code is checked before the amount"
do apply_coupon("WINTER5", cents: 1500)
expect fails Unknownexpect result == 4500. The happy path: 10 percent off 50.00.expect fails Unknown.apply_couponfails withCouponError, andUnknownis one of its variants. You name the variant only, without its fields."a small cart is BelowMinimum, even with a good code". The second failure path gets its own example."the code is checked before the amount". When both inputs are wrong, the order of the checks decides which failure the caller sees. An example pins that order down, so a later edit that swaps the checks fails a test.
$ una test .
example coupons "SPRING10 takes 10 percent off" ... ok
example coupons "an unknown code is Unknown" ... ok
example coupons "a small cart is BelowMinimum, even with a good code" ... ok
example coupons "the code is checked before the amount" ... ok
4 examples: 4 passed, 0 failed14.2.5 How expect fails behaves
14.2.5.1 What the report says when an expectation is wrong
The expectations of an example are checked in order, and the first that does not hold fails it. Two mistakes are common. Here are both, written on purpose:
example "SPRING10 on 50.00 is refused"
do apply_coupon("SPRING10", cents: 5000)
expect fails BelowMinimum
example "WINTER5 takes 5 percent off"
do apply_coupon("WINTER5", cents: 5000)
expect result == 4750$ una test .
example coupons "SPRING10 on 50.00 is refused" ... FAILED
src/coupons.una:32: expect fails BelowMinimum
the `do` line completed with `4500`
example coupons "WINTER5 takes 5 percent off" ... FAILED
src/coupons.una:36: expect result == 4750
the `do` line failed with `Unknown("WINTER5")`, so `result` has no value
2 examples: 0 passed, 2 failedexpect fails, and the call succeeded. The report gives the value it returned instead:4500. A cart of 50.00 meets the minimum, so the example was wrong, not the code.expect result, and the call failed. There is noresultto compare, and the report gives the failure:Unknown("WINTER5").
14.2.5.2 A failure no expect fails line expects
A third rule closes the gap between those two mistakes. When the do line fails and no expect fails line expects it, the example fails, even if every other line held. A failure is never silently accepted. A failure nobody expected shows the report.
14.2.5.3 A failure stops the do line
A do line may nest several calls, and more than one of them may fail or use a service. Elsewhere, a call that can fail is the whole of its line (chapter 7); a do line is free of that rule. The calls run from left to right, the first failure ends the do line, and the example then checks its expect lines against that failure.
14.2.5.4 A failure as a value: do attempt
A do line takes no handling clause. Handle the unknown code on the do line of a new example, as a statement elsewhere would:
example "an unknown code, handled on the do line"
do apply_coupon("WINTER5", cents: 5000)
if error use 0
expect result == 0[U0101] Error: unexpected indentation, expected `expect`The example ends at the do line, so Una expects an expect line where the clause stands. To look at the failure as a value instead, put attempt in front of the call (section 7.4). The do line then gives a Result, Err for a failure, and an expect line can test its variant with is:
example "an unknown code, kept as a value"
do attempt apply_coupon("WINTER5", cents: 5000)
expect result is Errexample coupons "an unknown code, kept as a value" ... ok
5 examples: 5 passed, 0 failedPrefer expect fails Unknown: it names the variant and reads as the rule. Use do attempt when the example needs the Result itself.
14.2.6 Choosing what to expect
Which to use:
| The case… | Write |
|---|---|
| Returns a value you know | expect result == … |
| Must fail, and the variant matters | expect fails V |
| Fails, and you also care what it did before failing | expect fails V and expect performed or expect not performed (section 14.3) |
| Has two wrong inputs at once | one example that pins which failure wins |
14.2.7 Check yourself: failures
A new example, at the end of the coupon step:
example "a small cart with a lowercase code is BelowMinimum"
do apply_coupon("vip25", cents: 1500)
expect fails BelowMinimumThe cart is under 20.00. Does the example pass?
Show the answer
No:
example coupons "a small cart with a lowercase code is BelowMinimum" ... FAILED
src/coupons.una:48: expect fails BelowMinimum
the `do` line failed with `Unknown("vip25")`Codes are compared exactly, so vip25 is not VIP25, and the code is checked before the amount. The call fails with Unknown("vip25"), which is not the variant the example expects. The example of the order of checks, "the code is checked before the amount", states the same rule.
Next:14.3 Fakes: given, expect performed and expect not performed