Home / Learn / 14 Testing

Release v0.4.0Edition 0.2

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:

steps/08-happy-only/src/coupons.unacheckruntestuna
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 == 4500

una run . prints:

Output
SPRING10: 4500, WINTER5: 5000
Terminal
$ una test .
example coupons "SPRING10 takes 10 percent off" ... ok

1 example: 1 passed, 0 failed

Every 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:

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:

steps/09-failures/src/coupons.unacheckruntestuna
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 Unknown
  1. expect result == 4500. The happy path: 10 percent off 50.00.
  2. expect fails Unknown. apply_coupon fails with CouponError, and Unknown is one of its variants. You name the variant only, without its fields.
  3. "a small cart is BelowMinimum, even with a good code". The second failure path gets its own example.
  4. "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.
Terminal
$ 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 failed

14.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:

steps/10-misread/src/coupons.unauna
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
Terminal
$ 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 failed

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:

steps/11-clause-on-do/src/coupons.unauna
example "an unknown code, handled on the do line"
  do apply_coupon("WINTER5", cents: 5000)
    if error use 0
  expect result == 0
Diagnostic
[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:

steps/12-attempt-on-do/src/coupons.unauna
example "an unknown code, kept as a value"
  do attempt apply_coupon("WINTER5", cents: 5000)
  expect result is Err
Output
example coupons "an unknown code, kept as a value" ... ok

5 examples: 5 passed, 0 failed

Prefer 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:

steps/13-wrong-order/src/coupons.unauna
example "a small cart with a lowercase code is BelowMinimum"
  do apply_coupon("vip25", cents: 1500)
  expect fails BelowMinimum

The cart is under 20.00. Does the example pass?

Show the answer

No:

Output
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