---
title: "14.2 Testing failures: expect fails"
url: https://una-lang.org/en/learn/testing/testing-failures-expect-fails/
release: v0.4.0
edition: "0.2"
---

# 14.2 Testing failures: expect fails

## 14.2.1 What a failure path is

A function that can fail ([section 7.2](https://una-lang.org/en/learn/failure/declaring-a-failure-fails-and-fail/#s7-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](https://una-lang.org/en/learn/failure/testing-it/#s7-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:

```una include="steps/08-happy-only/src/coupons.una" title="steps/08-happy-only/src/coupons.una" verified="check, run, test"
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:

```text include="steps/08-happy-only/expected/output.txt"
SPRING10: 4500, WINTER5: 5000
```

```text include="steps/08-happy-only/expected/commands/test.txt"
$ 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:

- **`expect fails Unknown`** holds when the `do` line failed with the variant `Unknown`.
- **Name the variant only,** without its fields: `expect fails Unknown`, not `expect fails Unknown("WINTER5")`.
- **The variant is of the `do` call's error kind,** the kind its `fails` clause names.
- **The `do` line needs no handling clause.** Whatever it fails with, the example catches it, and `expect fails` names the variant. A handling clause such as `if error use` under a `do` line is a syntax error, U0101. When you want the failure as a value instead, `do attempt f(…)` gives a `Result` ([section 7.4](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4)), which `expect result is Err` can test. [A failure as a value](#a-failure-as-a-value-do-attempt) 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:

:::steps
```una include="steps/09-failures/src/coupons.una" title="steps/09-failures/src/coupons.una" verified="check, run, test"
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.
:::

```text include="steps/09-failures/expected/commands/test.txt"
$ 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:

```una include="steps/10-misread/src/coupons.una#L30-L36" title="steps/10-misread/src/coupons.una"
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
```

```text include="steps/10-misread/expected/commands/test.txt"
$ 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
```

- **`expect 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 no `result` to 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](https://una-lang.org/en/learn/testing/fakes-given-expect-performed-and-expect-not-performed/#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](https://una-lang.org/en/learn/failure/common-mistakes/#nesting-a-call-that-can-fail-u3013)); 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:

```una include="steps/11-clause-on-do/src/coupons.una#L46-L49" title="steps/11-clause-on-do/src/coupons.una"
example "an unknown code, handled on the do line"
  do apply_coupon("WINTER5", cents: 5000)
    if error use 0
  expect result == 0
```

```text include="steps/11-clause-on-do/expected/rendered.txt#L1"
[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](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4)). The `do` line then gives a `Result`, `Err` for a failure, and an `expect` line can test its variant with `is`:

```una include="steps/12-attempt-on-do/src/coupons.una#L46-L48" title="steps/12-attempt-on-do/src/coupons.una"
example "an unknown code, kept as a value"
  do attempt apply_coupon("WINTER5", cents: 5000)
  expect result is Err
```

```text include="steps/12-attempt-on-do/expected/commands/test.txt#L6-L8"
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

:::decide
**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](https://una-lang.org/en/learn/testing/fakes-given-expect-performed-and-expect-not-performed/#s14-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:

```una include="steps/13-wrong-order/src/coupons.una#L46-L48" title="steps/13-wrong-order/src/coupons.una"
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?

:::answer Show the answer
No:

```text include="steps/13-wrong-order/expected/commands/test.txt#L6-L8"
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.
:::
