Home / Docs / Language guide / Examples as tests

example

Release v0.4.0Edition 0.1 and laterU1001U1002U3001U3014U3020U3021

What it does

An example is executable evidence of behavior: a small test written beside the code it exercises, which una test runs. This is the declaration of editions 0.1 and 0.2; edition 0.3 writes it test, with the same lines and rules, and rejects example with a rewrite that una fix applies. Edition 0.4 writes it test as well, and there example is an ordinary name.

Learn more: Examples: do and expect, Fakes: given, expect performed and expect not performed and Testing failures: expect fails.

Its lines:

una
module shop

pub kind OrderError = | TooMany

pub add_units(units: Int) -> Int
  fails OrderError
=
  if units > 100 then fail TooMany else units + 1

example "adding a unit"
  do add_units(1)
  expect result == 2

example "too many units"
  do add_units(101)
  expect fails TooMany

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
example_decl    = "example" text_lit NEWLINE INDENT
                    { "given" cap_ref "=" handler_call NEWLINE }
                    "do" line_expr NEWLINE
                    expectation { expectation }
                  DEDENT ;
handler_call    = lower_ident "(" [ args ] ")" ;
expectation     = "expect" ( "fails" upper_ident
                           | [ "not" ] "performed" cap_ref "." lower_ident
                           | line_expr ) NEWLINE ;

The lines mean:

Line Meaning
given @x = h(args) Install handler h as capability @x for this example
do e The expression under test. It may have effects or fail; it needs no handling clauses
expect e e is a Bool expression over result; it must evaluate to true
expect fails V do failed with variant V
expect performed @x.op The trace (the record, in order, of the effects the run performed) contains at least one completed or failed op on binding @x
expect not performed @x.op The trace contains no op on binding @x

An example has at least one expect line.

Examples

A handler stands in for a capability, and the trace shows what the code did:

una
module shop

pub capability Log
  op write(line: Text) -> Unit

pub note(line: Text) -> Unit
  uses @log: Log[write]
=
  @log.write(line)

handler quiet() for Log
  op write(line) = unit

example "notes once"
  given @log = quiet()
  do note("order 42 shipped")
  expect performed @log.write

Examples cannot use host capabilities, so they are deterministic. A capability the code needs comes from given:

una
-- fails with U3014
module shop

pub greet(name: Text) -> Unit
  uses @console: Console[print]
=
  @console.print("hi {name}")

example "greets"
  do greet("ann")
  expect result == unit

Edge cases

Every capability do needs has a given:

una
-- fails with U3001
module shop

pub capability Log
  op write(line: Text) -> Unit

pub note(line: Text) -> Unit
  uses @log: Log[write]
=
  @log.write(line)

example "missing handler"
  do note("order 42 shipped")
  expect result == unit

expect performed names a declared operation:

una
-- fails with U1001
module shop

pub capability Log
  op write(line: Text) -> Unit

pub note(line: Text) -> Unit
  uses @log: Log[write]
=
  @log.write(line)

handler quiet() for Log
  op write(line) = unit

example "notes"
  given @log = quiet()
  do note("order 42 shipped")
  expect performed @log.erase

Names are unique per module:

una
-- fails with U1002
module shop

pub double_price(cents: Int) -> Int = cents * 2

example "doubles"
  do double_price(2)
  expect result == 4

example "doubles"
  do double_price(3)
  expect result == 6

Further rules:

Diagnostics

Edition

Examples are the same in editions 0.1 and 0.2. In edition 0.3 the declaration is written test (ADR 0105): an example declaration there is U0103 with the exact rewrite of the keyword, which una fix applies. In edition 0.4 example is an ordinary name, with no U0103 and no rewrite (ADR 0105, amendment of 2026-11-05). Edition 0.3 also adds boundaries (modules whose authority una.toml limits, see [boundaries]): the given handlers of an example of a boundary module count against its ceiling (U3021), and a do line that calls into a boundary from outside it grants it nothing by name (U3020). Learn more: A ceiling for a module: boundaries.

Normative source