---
title: "Examples as tests"
url: https://una-lang.org/en/docs/language/examples/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# Examples as tests

```una
module demo

import std.testing (fake_hash)

pub kind Availability = SoldOut | Few | Open

pub kind Registration
  name: Text
  status: Availability

pub kind StoreError = Timeout | Corrupted

pub kind CheckInError = NotRegistered | Unavailable

pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

pub capability Audit
  op record(key: internal Hashed, status: Availability) -> Unit
    fails StoreError
    accepts internal

pub check_in(key: internal Hashed) -> Availability
  uses @registrations: Registrations[find]
  uses @audit: Audit[record]
  fails CheckInError
=
  let registration = @registrations.find(key)
    if error fail Unavailable
    if none fail NotRegistered
  @audit.record(key, status: registration.status)
    if error fail Unavailable
  registration.status

handler one_registration(r: Registration) for Registrations
  op find(key) = Some(r)

handler no_registrations() for Registrations
  op find(key) = None

handler audit_log() for Audit
  op record(key, status) = unit

example "a registered attendee is checked in and audited"
  given @registrations = one_registration(Registration(name: "Ana", status: Open))
  given @audit = audit_log()
  do check_in(fake_hash(1))
  expect result is Open
  expect performed @audit.record

example "an unknown attendee fails and is not audited"
  given @registrations = no_registrations()
  given @audit = audit_log()
  do check_in(fake_hash(1))
  expect fails NotRegistered
  expect not performed @audit.record
```

| Line | Meaning |
| --- | --- |
| `given @x = h(args)` | install handler `h` as `@x` for this example |
| `do e` | the expression under test |
| `expect e` | `e` is a `Bool` over `result` and must be `true` |
| `expect fails V` | `do` failed with variant `V` |
| `expect performed @x.op` | the effect trace contains at least one `op` on `@x` |
| `expect not performed @x.op` | the trace contains no `op` on `@x` |

- **No host capabilities.** Examples cannot use them (U3014); everything comes from `given`, so examples are deterministic.
- **`do` lines** may nest fallible and effectful calls, and any failure ends the example. They need no handling clauses. A `do` line has no editable binding, so a call with `edit` or `take` there is U3013: exercise it through a function that edits a local copy.
- **Names** are unique per module.
- **Isolation.** Each example runs in a fresh abstract machine. `una test --json` reports the outcome and the full effect trace, with labeled arguments redacted.
- **`std.testing`** (`fake_hash`) is usable only in examples and in handlers installed only by `given`, and only by calling it, never as a function value (U3015).

---


## Constructs

- [example](https://una-lang.org/en/docs/language/examples/example.md)
- [test](https://una-lang.org/en/docs/language/examples/test.md)
