Repository navigation
How a Demo Flows
One demoflow run takes a scenario through six stages, from checking that it can run at all to the finished video. Each stage reports its own status, and the run's status is derived from them, never from whether a video file exists.
The six stages, in order:
| Stage | Owner | What it covers |
|---|---|---|
readiness |
engine (and the CLI, for the app start) | the app answers; origins are allowed; a base URL exists for relative paths; every secret variable is set |
execution |
engine | the steps run in Chromium |
verification |
engine | the assertions (assertVisible, assertText) pass |
recording |
engine | the page video (source.webm) is written |
rendering |
renderer | the polished MP4 is composed from the video and the timeline |
storage |
— | always skipped today: runs are local only |
Each stage is pending, running, passed, failed or skipped. The run as a whole is:
| Run status | When |
|---|---|
completed |
no stage failed, none pending or running, no warnings |
completed_with_warnings |
the same, with warnings (for example a css locator) |
failed |
any stage failed |
running |
some stage is still pending or running |
Recording is separate from rendering: the engine captures a plain video and a timeline of what happened, and the renderer adds the cursor, zoom, captions and masks afterwards.
-
Load. The CLI finds the project root, loads
demoflow.config.json, resolves where artifacts go, validates the scenario and collects warnings. It gives the run an id such as20261018-200548-clfwzo(UTC time plus six random characters). -
App start. If the config has a
devCommandand itsreadyUrldoes not answer yet, the CLI starts the app, alongside the Chromium check (and first-use download). If the app never becomes ready,readinessfails with the app's last output, every other stage isskipped, and the run exits with code 2. -
Readiness. The engine checks every origin against
allowedOrigins, that each relativenavigatehas a base URL, and that eachvalueFrom.envvariable is set. The first problem failsreadinessandexecution,verificationandrecordingareskipped— no browser starts. -
Browser. Chromium launches, headless unless
--headed, with video recording at the viewport size.recordingisrunningfrom here. - Sync mark. Before the first step, the engine paints and clears a short full-page colour mark. The renderer later finds it in the video to line the video up with the timeline.
-
Steps.
executionruns, andverificationtoo when the scenario has assertions (otherwise it isskipped). The first failing step stops the run: an assertion failsverification, anything else failsexecution, and the other of the two becomesskipped. The failed step's index is recorded. -
Video. The browser context closes, which finalises the video — also after a failure.
recordingpasses, or fails withno video recorded. -
Files.
timeline.json,scenario.json,source.webmandresult.jsonare in the run directory. -
Render. If
source.webmexists, the renderer builds a render plan and composesrender/ffmpeg.mp4. A failed run is rendered too, with a failure watermark and an end card: the video is the evidence. -
Settle.
renderingandstoragestillpendingbecomeskipped, the status is derived again, andresult.jsonis replaced atomically. -
Report. The CLI prints a summary (or one JSON object with
--json), stops the app if it started it, and exits.
stateDiagram-v2
[*] --> readiness
readiness --> execution: passed
readiness --> settle: failed (exit 2)
execution --> recording: steps done or first failure
recording --> rendering: source.webm exists
recording --> settle: no video
rendering --> settle
settle --> [*]
verification runs alongside execution, over the same steps; storage is settled as skipped.
npx demoflow run demoflow/customers.demo.jsonThe exit code tells you which stage failed first:
| Exit | Meaning |
|---|---|
0 |
completed or completed_with_warnings
|
1 |
execution or verification failed |
2 |
readiness failed, or the input was invalid (scenario, config, origin, missing variable, app not ready) |
3 |
recording, rendering or storage failed, or rendering crashed |
130 / 143
|
interrupted by SIGINT / SIGTERM |
result.json holds every stage with its status, times and error:
{
"status": "failed",
"stages": {
"readiness": { "status": "passed" },
"execution": { "status": "passed" },
"verification": { "status": "failed", "error": { "message": "…", "stepIndex": 4 } },
"recording": { "status": "passed" },
"rendering": { "status": "passed" },
"storage": { "status": "skipped" }
}
}(Abridged: the real file also has runId, scenarioId, times, renders and warnings.)
The lifecycle itself has no switches. What it reads:
| From | Used by |
|---|---|
devCommand, baseUrl, allowedOrigins in demoflow.config.json
|
app start, readiness |
render.* in demoflow.config.json
|
rendering |
--headed, --base-url, --out, --json
|
browser, readiness, artifact location, output |
See Project Configuration and CLI Reference.
- A video existing does not mean success: the status comes from the stages.
- It never starts a browser when readiness fails.
- It does not retry a failed step; the first failure ends the run.
-
storageis not implemented: everything stays on your machine. - The CLI stops the app only if it started it.
-
Running Demos — the
runcommand in practice -
Run Artifacts —
result.json,timeline.jsonand the run directory - Rendering and Effects · Secrets and Masking · Architecture
- ADR-0004: recording is separate from rendering · ADR-0010: source video at viewport size
-
Spec 3: engine · Spec 5:
demoflow run· Spec 90:runstarts the app · Spec 19: clock sync mark
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference