Home / Docs / Specification
08. Requirements and tests
Status: Normative, v0.1.
1. Requirements
A requirement records a human or business statement with its origin and owner, so contracts can be traced to intent.
requirement EVENTS_3
text "An event with no remaining seats is always shown as sold out"
source policy "Box Office Handbook 2.1"
owner box_office
status active| Field | Values |
|---|---|
text |
The statement, as written by its source |
source |
human, policy "<document>", regulation "<document>", generated "<task reference>" |
owner |
Team or person accountable (lower snake case) |
status |
proposed or active |
Rules:
- Requirement identifiers are unique per package (U1002).
- A requirement with
source generatedMUST havestatus proposed(U1007). Agents may propose requirements; activating one requires a person to change its source tohuman,policyorregulation, which the semantic diff (v0.3) will surface. - Every identifier in a
derived fromclause MUST be declared in the package (U1006). - Functions derived from
proposedrequirements compile normally and are flagged in the build report.
una trace EVENTS_3 lists every function deriving from the requirement, its contract clauses and the verification status of each obligation. It reads the package in the current directory and checks it at tier 1, then prints the requirement (identifier, status, text, source, owner) and every function derived from it, by qualified name, with its requires and ensures clauses and the status of each of its obligations. With --json it prints {"schema":"una.trace/1","requirement":{...},"functions":[{"function":...,"requires":[...],"ensures":[...],"obligations":[{"id":...,"kind":...,"status":...,"goal":...}]}]}. The package's diagnostics, those of its project files included, are reported before the identifier is resolved, with exit code 1 (ADR 0036); in a package without diagnostics, an unknown identifier is a usage error (exit code 2), and an obligation that is not proven gives exit code 1 (ADR 0034).
2. Tests
Tests are executable evidence. They live next to the code they exercise and run with una test. (v0.3, ADR 0105.) In edition 0.3 the declaration is written test; editions 0.1 and 0.2 write it example, with the same body, and every rule of this section holds of a declaration under either keyword. (Edition 0.4, ADR 0105 amendment of 2026-11-05.) Edition 0.4 writes it test too, and there example is an identifier, not a declaration keyword (spec/01 §5). This chapter says "test" for both.
test "an unknown attendee fails and is not audited"
given @registrations = no_registrations()
given @audit = audit_log()
given @keys = fake_keys()
do check_in(sample_phone())
expect fails NotRegistered
expect not performed @audit.record| Line | Meaning |
|---|---|
given @x = h(args) |
Install handler h as capability @x for this test |
do e |
The expression under test. It MAY be effectful or fallible; 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 contains at least one completed or failed op on binding @x |
expect not performed @x.op |
The trace contains no op on binding @x |
stop after N |
(Edition 0.4, ADR 0116 rule 19.) The last line, optional: each for ever instance ends at the start of its own iteration N + 1, so do may run forever (spec/26 §8) |
Rules:
- Tests MUST NOT use host capabilities (U3014); every capability
doneeds comes fromgiven(U3001 if missing). This makes tests deterministic. expect elines withresultare allowed only whendocompleted normally; ifdofailed, such an expectation fails the test with the failure shown.- Test names are unique per module (U1002).
- Tests are type-checked, information-flow checked and verified like any other code, except for the sink exemption in spec/07 §4.
- The one-effect-per-line rule (U3013) does not apply to
dolines: they may nest fallible and effectful calls, evaluated left to right, and any failure ends the test. - Each test runs in a fresh abstract machine.
una test --jsonreports, per test, the outcome, the failed expectation if any and the full effect trace (spec/11 §5). - The expectations of a test are checked in order, and the first that does not hold fails it; then a
doline that failed with noexpect failsline fails it too. Anexpectline that does not mentionresultruns even whendofailed.expect performed @x.opholds when the trace has a completed or failedopevent of the instance ofgiven @x, andexpect not performed @x.opwhen it has none. An example's trace records the operations performed in quiet code too, but those of instances that quiet code installed (#1544), which a run's trace leaves out (spec/11 §5, spec/26 §6 rule 4, S-42). A test whose run aborts fails (ADR 0032).