Home / Docs / Language guide / Examples as tests

test

What it does

A test is executable evidence of behavior: a small test written beside the code it exercises, which una test runs. It is the declaration of editions 0.3 to 0.5; editions 0.1 and 0.2 write it example, with the same lines and rules.

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

Its lines:

una
-- edition 0.3
module shop

pub kind OrderError = | TooMany

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

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

test "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
test_decl       = "test" 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 test
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

A test has at least one expect line.

Examples

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

una
-- edition 0.3
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

test "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
-- edition 0.3
module shop

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

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

Edge cases

Every capability do needs has a given:

una
-- fails with U3001
-- edition 0.3
module shop

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

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

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

expect performed names a declared operation:

una
-- fails with U1001
-- edition 0.3
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

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

Names are unique per module:

una
-- fails with U1002
-- edition 0.3
module shop

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

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

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

Further rules:

Diagnostics

Edition

In edition 0.3 the declaration is written test, and test is a keyword there: a local named test is renamed by una fix to test_value, and a function, field, handler or module named test needs another name (U0101). An example declaration in an edition 0.3 package is U0103, "example is written test in edition 0.3", and una fix rewrites the keyword; the body does not change. Editions 0.1 and 0.2 keep example and test as a name. In edition 0.4 the declaration is test too, and example is an ordinary name: a function, a local, a field or a module may be called example, and a line example "..." is a plain syntax error (U0101) with no rewrite, since una fix rewrites example in edition 0.3 packages only (ADR 0105, amendment of 2026-11-05). una test prints test <module> "<name>" ... ok and <n> tests: ... for an edition 0.3 package, and its --json is una.test/2, with the key tests where una.test/1 has examples. 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