Skip to content

How a Demo Flows

Archi edited this page Oct 18, 2026 · 1 revision

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.

Overview

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.

How it works

  1. 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 as 20261018-200548-clfwzo (UTC time plus six random characters).
  2. App start. If the config has a devCommand and its readyUrl does not answer yet, the CLI starts the app, alongside the Chromium check (and first-use download). If the app never becomes ready, readiness fails with the app's last output, every other stage is skipped, and the run exits with code 2.
  3. Readiness. The engine checks every origin against allowedOrigins, that each relative navigate has a base URL, and that each valueFrom.env variable is set. The first problem fails readiness and execution, verification and recording are skipped — no browser starts.
  4. Browser. Chromium launches, headless unless --headed, with video recording at the viewport size. recording is running from here.
  5. 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.
  6. Steps. execution runs, and verification too when the scenario has assertions (otherwise it is skipped). The first failing step stops the run: an assertion fails verification, anything else fails execution, and the other of the two becomes skipped. The failed step's index is recorded.
  7. Video. The browser context closes, which finalises the video — also after a failure. recording passes, or fails with no video recorded.
  8. Files. timeline.json, scenario.json, source.webm and result.json are in the run directory.
  9. Render. If source.webm exists, the renderer builds a render plan and composes render/ffmpeg.mp4. A failed run is rendered too, with a failure watermark and an end card: the video is the evidence.
  10. Settle. rendering and storage still pending become skipped, the status is derived again, and result.json is replaced atomically.
  11. 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 --> [*]
Loading

verification runs alongside execution, over the same steps; storage is settled as skipped.

Using it

npx demoflow run demoflow/customers.demo.json

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

Settings

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.

Limits / what it never does

  • 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.
  • storage is not implemented: everything stays on your machine.
  • The CLI stops the app only if it started it.

See also

Clone this wiki locally