nordisk/facett

The headless harness — for idiots

Class: idiot. Every step, nothing assumed. Goal: run the whole test-matrix and robot suite from a cold shell and read the result — no window, no clicking. Migrating one component to the testable Elm shape is a different job, walked in elm-for-idiots.md (its Steps 7–8 use the harness). This one is about running the whole battery.

What you need first

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

cd /run/media/rickard/T9/git/facett

• For the picture-taking (robot) tests you need a GPU or software renderer. If you don't have one, those tests skip themselves — that is fine, the rest still run.

Step 1 — run the plain tests (no pictures, no matrix)

Type and press Enter:

cargo test

Wait. Green test result: ok lines = good. This runs every component's headless state + render checks. It does NOT take screenshots or write matrix rows yet.

Step 2 — collect the matrix rows

The matrix is a JSON file with one row per real check. Tell the tests where to write it, and turn the feature on. Type and press Enter (one long command):

NORNIR_TESTMATRIX_OUT=$PWD/target/nornir-functional.json cargo test --features testmatrix

When it finishes, look at the file. Type and press Enter:

cat target/nornir-functional.json

Each line is one check: a component, a check name, and "status" PASS or FAIL. A FAIL is a red cell — a real thing that is broken (a blank render, a dead map).

Step 3 — run the robot suite (the picture tests)

These fire up each component for real and photograph it. Type and press Enter:

cargo test -p facett-demo --test robot_deck -- --nocapture

Read the lines it prints. Each tab prints something like:

[robot] tab=graph        spoke=0.031 hf=0.112 cov=0.140  → /tmp/.../tab_graph.png

• spoke near 0 = clean. spoke above 0.45 = a smear (bad).
• The PNGs it names are real images — open them to see exactly what rendered.

If you see no wgpu backend … skipped, you have no GPU; that is not a failure.

Step 4 — the "what actually ran" list

This drives the whole demo and writes a list of every tab and button that really executed. Type and press Enter:

cargo test -p facett-demo --test pop_ran_list -- --nocapture

Then read the list it wrote. Type and press Enter:

cat /home/rickard/.cache/claude-build/facett-demo-ran-list.md

Every row with ✅ is a surface that ran. A missing row is a control that never fired — that is the bug those tests exist to catch.

Step 5 — facett's own quality matrix (build/clippy/fmt/audit)

This one shells cargo per aspect, so it is an example, not a test. Type and press Enter:

cargo run -p facett --example quality_matrix

It prints a grid at the end: a ✓ per aspect that passed, a red ✗ per aspect that failed, and writes the rows to target/quality-matrix.jsonl.

Step 6 — read the whole matrix as one grid

nornir test reads the JSON from Step 2 back into one matrix. From the nornir checkout, type and press Enter:

cd /run/media/rickard/T9/git/nornir && cargo run -p nornir -- test

Green everywhere = every component renders real data with real geometry, every control ran, no frame smeared. A red cell names exactly which component × check to go fix.

That's the whole battery: plain tests → matrix rows → robot pictures → the ran-list → the quality grid → the combined matrix. Nothing was clicked by hand.