---
title: "18.5 Running, testing and building"
url: https://una-lang.org/en/learn/tools/running-testing-and-building/
release: v0.4.0
edition: "0.2"
---

# 18.5 Running, testing and building

## 18.5.1 What running, testing and building are

una can execute a package in three ways:

- **Running** executes `main`. `una run .` does it inside una itself, which reads the checked program and carries it out step by step. A program that executes another program this way is an **interpreter**.
- **Testing** executes every `example` of the package ([chapter 14](https://una-lang.org/en/learn/testing/)), each on its own, and compares the results with what the examples expect.
- **Building** turns the package into a **native executable**: a file of instructions for the machine's processor, which runs on its own, without una. Turning code into such a file is **compiling**, and a program that does it is a compiler.

## 18.5.2 Why three commands

Each answers its own need. While you write, `una run .` shows what the program does right away. Before a change is done, `una test .` checks the numbers against values a person worked out. To ship, `una build .` gives an executable that the store's machines run without una installed.

## 18.5.3 How to write them

### 18.5.3.1 `una run .` and `--grant`

`una run .` runs `main` of the module that `[run] entry` names, with the grants of `[run] grants` ([chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2)). `una run --grant <spec> .` adds a grant for one run, such as `--grant clock`, on top of those of `una.toml`.

### 18.5.3.2 `una test .`

`una test .` runs every example and prints one line for each, then a count:

```text include="steps/08-proven/expected/commands/test.txt"
$ una test .
example discount "30 percent off a lamp" ... ok
example discount "a typed percent above 90 is OutOfRange" ... ok

2 examples: 2 passed, 0 failed
```

### 18.5.3.3 `una build .`

`una build .` compiles the package into a native executable, after the same checks:

```sh
una build .
```

```text include="steps/08-proven/expected/commands/build.txt"
$ una build .
built target/una/discount
```

### 18.5.3.4 With `--json`

With `--json`, `una run .` prints the run as one document: the status, the lines printed, the failure if any, and the **trace** of the run, the list of every operation it performed. This is a different thing from `una trace`, which follows a requirement to the code:

```text include="steps/08-proven/expected/commands/run.txt"
$ una --json run .
{"schema":"una.run/1","tier":1,"status":"ok","output":["LAMP-01 1393, DESK-02 11000"],"failure":null,"diagnostics":[],"trace":[{"seq":1,"instance":"host:Console","capability":"Console","op":"print","args":{"line":"\"LAMP-01 1393, DESK-02 11000\""},"outcome":{"kind":"ok","value":"unit"}}]}
```

The trace is what the program asked of the outside world, in order, with the arguments and the outcome of each operation. `una --json test .` gives each example its outcome, its result and its own trace:

```text include="steps/08-proven/expected/commands/test-json.txt"
$ una --json test .
{"schema":"una.test/1","tier":1,"redacted":false,"diagnostics":[],"examples":[{"module":"discount","name":"30 percent off a lamp","outcome":"pass","reason":null,"expectation":null,"result":{"kind":"ok","value":"1393"},"trace":[]},{"module":"discount","name":"a typed percent above 90 is OutOfRange","outcome":"pass","reason":null,"expectation":null,"result":{"kind":"fail","variant":"OutOfRange","value":"OutOfRange(95)"},"trace":[]}],"passed":2,"failed":0}
```

## 18.5.4 Every command checks first

`una run`, `una test` and `una build` check the package first, at tier 1, and run nothing when the check reports an error. On the package with the wrong word, the run is `rejected`: nothing ran, `output` and `trace` are empty, and `diagnostics` holds the reason:

```text include="steps/09-refuted/expected/commands/run.txt"
$ una --json run .
{"schema":"una.run/1","tier":1,"status":"rejected","output":[],"failure":null,"diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"postcondition of `sale_price` is refuted","primary":{"file":"src/discount.una","start":{"line":24,"col":29},"end":{"line":24,"col":34}},"related":[{"file":"src/discount.una","start":{"line":20,"col":11},"end":{"line":20,"col":25},"message":"ensures clause"}],"obligation":{"id":"ob-8a05af02a5f7","kind":"postcondition","goal":"result >= cost","status":"refuted"},"counterexample":{"bindings":[{"name":"cost","value":1},{"name":"off","value":0},{"name":"price","value":0},{"name":"result","value":0}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard or an arm so that the failing path returns a value for which `result >= cost` holds","edit":null},{"rank":2,"escape_cost":0,"description":"adjust the `ensures` clause","edit":null}],"explain":"una explain U5001"}],"trace":[]}
```

So a program that runs, or an executable that exists, is always one that checked.

## 18.5.5 How running, testing and building behave

- **The status of a run.** `ok` for a run that returned, `failed` when `main` failed with its error kind, `aborted` when the run was stopped, by a limit ([chapter 16](https://una-lang.org/en/learn/memory/limits-call-depth-and-memory/#s16-4) shows one) or another runtime error, and `rejected` when the checks failed and nothing ran.
- **The examples run alone.** Each example gets only the handlers its `given` lines install, so an example never reaches the console or a real service by accident.
- **The executable.** `una build .` writes it under the package, at `target/una/<name>`, with `<name>` from `[package] name`. It runs `main` with the grants of `una.toml` built in, takes further `--grant` flags, and prints what `una run .` prints. **Linking** is the last step of a build: it joins the compiled code with the **runtime library**, the code that every Una executable shares. On a Mac, `una` links with a **linker** built into it and needs no other program. On Linux, it links through the system's C compiler, `cc` (gcc or clang, with the C library's development files), which must be on the path, the list of directories where the terminal looks for programs. It builds for the machine it runs on.

## 18.5.6 Exit codes

Every command of `una` ends with an **exit code**, the number the terminal receives when the command ends ([What a tool is](https://una-lang.org/en/learn/tools/check-format-and-fix/#what-a-tool-is)), and one of four:

| Code | Meaning |
| --- | --- |
| 0 | Success: no error, every obligation proven, every example passed |
| 1 | The output holds at least one error with a code, an obligation that is not proven, or a failed example |
| 2 | A usage error: the command line itself is wrong, such as an unknown flag or a path with no package; it is printed on stderr, without a code |
| 3 | An internal error of una itself, U8001 |

So `una check .` exits with 0 when the package checks, and with 1 when it reports a problem. `una run .` exits with 1 when the run is not `ok`, and `una test .` with 1 when an example fails. Another program that runs una for you, such as a release script or a code editor, tells success from failure by this number, without reading the text. The exit code does not depend on `--json`: the document and the text say the same thing.

## 18.5.7 Choosing a command

The table matches each question of this chapter to the command that answers it:

:::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| Know whether the package is right, fast, while you type | `una check --tier 0 .`, or an editor with `una lsp` |
| Know whether it is right, proofs included | `una check .` |
| Apply the repairs that are exact | `una fix --dry-run .`, then `una fix .` |
| See what was proven, and for which requirement | `una obligations .`, `una trace <requirement>` |
| See what a function promises, inferred clauses included | `una contract <module.function>` |
| Review what a package may do and trusts | `una report .` |
| Run it, test it, ship it | `una run .`, `una test .`, `una build .` |
:::

## 18.5.8 Check yourself: an example with the wrong number

Someone worked out 30 percent off 19.90 by hand and wrote 13.90:

```diff include="steps/08-proven..steps/17-failing-example:src/discount.una" context="1" title="src/discount.una"
--- a/src/discount.una
+++ b/src/discount.una
@@ -46,3 +46,3 @@
   do sale_price(1990, cost: 1200, off: 30)
-  expect result == 1393
+  expect result == 1390
 
```

Does `una check .` accept the package? What does `una test .` print?

:::answer Show the answer
`una check .` accepts it: an example's `do` line must check, but whether its expectation holds is decided by running it. `una test .` runs it and reports the failure, with the line, the expectation and the value the code gave:

```text include="steps/17-failing-example/expected/commands/test.txt"
$ una test .
example discount "30 percent off a lamp" ... FAILED
  src/discount.una:47: expect result == 1390
  it is false, with `result` = `1393`
example discount "a typed percent above 90 is OutOfRange" ... ok

2 examples: 1 passed, 1 failed
```

The code computes 1393, which is right: 1990 - 1990 * 30 / 100 is 1990 - 597. The example was wrong, so the fix is in the example. A failed example says that the code and the person disagree; reading the value tells you which one is wrong.
:::
