🎬 saga — for idiots
Class:
idiot. Every step, nothing assumed. Goal: click ⏺ Record, move through the app, click ⏹ Stop, then click ▶ Replay — and watch the app re-drive itself green. If you already know your way around a terminal, readsaga-guide.mdinstead. The what is insaga-design.md.
saga is a tape recorder for using the app. You press record, you click around like a normal user, you press stop — and saga saves everything you did. Later you press replay and saga does the exact same clicks again, all by itself, and tells you green (it still works) or red (something you clicked is gone).
Why is that useful? Because if a future change accidentally removes a button you rely on, replaying your saved journey turns red and points right at it. It's a test you made just by using the app.
You press Enter after every command, and you click buttons in the app window.
Step 1 — start the app with recording turned on
Recording is off unless you switch it on when you start the app (so the normal app never wastes time recording). Open a terminal and type:
cd ~/git/nornir
cargo run --features "viz saga" --bin nornir-uiA window opens — that's nornir's viz (its dashboard). Wait for it to settle.
The magic words are
--features "viz saga". Thesagapart is what turns the tape recorder on. Without it, the buttons below do nothing.
Step 2 — find the recorder
In the app window:
- Click the 🧪 Test tab at the top.
- Find the section 🎬 Saga Sessions (record/replay) and click to expand it.
You'll see a ⏺ Record button. That's the recorder.
Step 3 — press ⏺ Record
Click ⏺ Record.
It now says something like "recording — navigate the viz, then ⏹ Stop". saga is watching. Everything you click from here is being taped.
Step 4 — move through the app
Just use it. Click a few tabs along the top, for example:
- click 🗂 Funnel
- click 🧵 Timeline
- click back to 🧪 Test
Each tab you open is one movement on the tape. Three or four clicks is plenty.
Step 5 — press ⏹ Stop
Go back to the 🎬 Saga Sessions section. The button now says ⏹ Stop (in red). Click it.
It saves your journey and shows something like "stopped — wrote 3 event(s) to saga_events". Your journey is now saved. A new row appears in the list below — that row is your recorded session.
Step 6 — press ▶ Replay and watch it re-drive itself green
In the list, your session row has a ▶ Replay button. Click it.
saga now takes the clicks you recorded and runs them again — automatically — against a fresh copy of the app. Underneath, it shows something like "last replay: session … → 3 step(s) → 3 matrix row(s)". Green rows mean every button you clicked is still there and still works. You just turned five seconds of clicking into a repeatable test. 🎉
What "red" means (and why you want it)
Imagine someone later removes one of the buttons you clicked. Replay your saved session again — the step for that button turns red, because saga went looking for it and it wasn't there. That red is saga doing its job: it caught a change that broke your journey. Green = your path still works. Red = something you used is gone.
Bonus — read your journey as a route map (terminal)
Every saved session has an id (the funny string in the row). In a terminal you can ask saga to print your journey as a route map:
nornir saga path <your-session-id>It lists the pages you visited in order. If you type an id that doesn't exist, it just says there are no events — it won't crash.
If something goes wrong
- ⏺ Record does nothing / no session appears after ⏹ Stop → you started the app without
saga. Close it and start again withcargo run --features "viz saga" --bin nornir-ui. - ⏹ Stop says "remote persist: phase 2" → your viz is in remote mode. Saving only works in a local viz for now; start a local one.
- ▶ Replay is greyed out → that session had nothing clickable to replay (e.g. it only recorded an error). Record a new one where you actually click tabs/buttons.
That's the whole thing: ⏺ Record → click around → ⏹ Stop → ▶ Replay → green. You made a test without writing a single line of code.