Home / Learn / 18 Tools

Release v0.4.0Edition 0.2

18.5 Running, testing and building

Page 6 of 11

18.5.1 What running, testing and building are

una can execute a package in three ways:

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). 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:

Terminal
$ 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 .
Terminal
$ 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:

Terminal
$ 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:

Terminal
$ 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:

Terminal
$ 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

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), 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:

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:

src/discount.unadiff
--- 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?

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:

Terminal
$ 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.

Next:18.6 Day-to-day: price tags for a sale