nordisk/nornir

The test function — for idiots

Class: idiot. Every step, nothing assumed. Goal: from a cold shell to a green test matrix you can see, then a bench and a coverage number. If you already know the CLI, read test-guide.md instead — this one spells out every keystroke. Bench-vs-test in one page: bench-vs-test-for-idiots.md.

What you need first

• A terminal (the black window where you type commands).
• The nornir repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/nornir

• The nornir program built and on your PATH. Check it — type and press Enter:

nornir --help

If that prints help text, you are ready. If it says "command not found", build it first: type and press Enter:

cargo build --release --bin nornir

then use ./target/release/nornir everywhere below instead of plain nornir.

Step 1 — see every test WITHOUT running anything

Type and press Enter:

nornir test list nornir

This prints the matrix: one line per test, each ending in ok, fail, or X. X means the test exists but has never been run. Nothing was compiled — this list is free. If you only want the ones that have never run, type and press Enter:

nornir test list nornir --not-run

Step 2 — actually run the tests

Type and press Enter:

nornir test run nornir

This compiles and runs the default aspects — build, unit, doctest, clippy, fmt, audit — and saves every result. It prints a summary line at the end. Green everywhere = you are done with this step. Red = one aspect failed; the line names which test and why.

Want it faster? Run just the quick lint aspects — type and press Enter:

nornir test run nornir --aspects fmt,clippy

The big, slow tests (the ones that download files or spin the fans) are skipped by default. To include them, add --heavy at the end, like nornir test run nornir --heavy. You almost never need this. Do NOT add it unless you were told to.

Step 3 — read the results back

Type and press Enter:

nornir test history nornir

This lists past runs, newest at the top, each marked green or red with pass/fail counts. Add --json --limit 3 if you want the raw data for the last three runs.

Step 4 — see it in a window (optional)

Type and press Enter:

nornir viz

A window opens. Click the 🧪 Test tab at the top. You see the same green/red board — a list of runs on the left, the selected run's tests coloured on the right. Close the window when done. Nothing here is different from what Step 3 printed; the window is just prettier.

Step 5 — measure speed (a bench)

A test asks "is it correct?"; a bench asks "how fast?". They are different. To run a repo's benches, type and press Enter (using a repo that HAS benches, e.g. znippy):

nornir bench run znippy

Each bench announces itself with a bench: … line as it runs and finishes with a number (MB/s, rows/s, ms). Read them back — type and press Enter:

nornir bench history-show znippy

Step 6 — measure how much code the tests touched (coverage)

Type and press Enter:

nornir coverage nornir

This runs the tests under a measuring tool and prints a table: one overall percentage, then a row per crate, then the worst-covered files. If it complains that a tool is missing, it prints the exact two commands to install it — copy them, run them, then try again. To also see the ui / gRPC / emitter breakdown, add --boundary at the end.

Step 7 — what "green" really means

You now have: a visible matrix (Step 1), a real run (Step 2), history (Step 3), a bench number (Step 5), and a coverage percentage (Step 6). A release checks all of these at once — if ANY test is red, or a bench got slower, or coverage misses a required surface, the release stops. That is the whole point: one gate, many checks, all green or the release does not ship.

That's the whole tour. You ran a GUI's tests without ever needing to click a real button, measured speed, and measured coverage — all from the terminal.