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:
givenlines install handlers (Una code that stands in for a capability, such as a fake store) for the capabilities (named authority over something outside the program, such as the console or a store) the code needs;doruns the expression under test;expectlines state what must hold: of its result, of its failure, or of the effects (actions outside the program, such as printing) it performed.
-- 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 TooManyForms
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.
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:
-- 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.writeExamples cannot use host capabilities, so they are deterministic. A capability the code needs comes from given:
-- 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 == unitEdge cases
Every capability do needs has a given:
-- 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 == unitexpect performed names a declared operation:
-- 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.eraseNames are unique per module:
-- 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 == 6Further rules:
- Checked like code. Examples are type-checked, checked for where labeled data flows, and verified like any other code. Only
expectlines are exempt from sink checks (the checks that labeled data reaches only places that accept it), since they observe values for the test harness. dolines may nest calls. The one-effect-per-line rule does not apply to them: calls that can fail or have effects are evaluated left to right, and any failure ends the example.- Order of expectations. They are checked in order, and the first that does not hold fails the example. An
expectoverresultafter a faileddofails it with the failure shown; adothat failed with noexpect failsline fails it too. Anexpectline that does not mentionresultstill runs after a faileddo, and an example whose run aborts fails. - Fresh runs. Each example runs in a fresh abstract machine (the model of a run that the specification defines), with nothing left from another example.
una test --jsonreports, per example, the outcome, the failed expectation if any, and the full effect trace.
Diagnostics
- U1001:
expect performednames an operation the capability does not declare. - U1002: an example name used twice in a module.
- U3001: a capability
doneeds that nogivenbinds. - U3014: an example that needs a host capability.
- U3020: in edition
0.3, adoline that calls a boundary function that needs a capability; adoline takes nowith, so it grants nothing. - U3021: in edition
0.3, agivenhandler of an example of a boundary module beyond the module's ceiling.
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
- spec/08 §2: tests, rules 1 to 7; spec/01 §5: the keyword
testandexamplein edition0.3. - spec/02 §5: the grammar.
- spec/05 §9 rule 5: operations named in examples, and, in edition
0.3, examples of boundary modules. - spec/07 §4: the sink exemption; spec/04 §4: one effect per line.
- spec/11 §5: traces; spec/13 §5:
una test. - Decision records: ADR 0105, the declaration is written
testin edition0.3; ADR 0032, for the order of expectations after a faileddo.