Skip to content

Running Demos

Archi edited this page Oct 18, 2026 · 1 revision

Running Demos

demoflow run turns one scenario file into a verified demo video. It can start your app, drives Chromium through the steps, checks the assertions, and renders the recording to an MP4. demoflow validate only checks a scenario against the schema and never opens a browser.

Overview

A run is local. Everything happens on your machine, and the output goes into a run directory under the DemoFlow home (see Run Artifacts). Each run reports a status for every stage. A failed verification still renders a video, because that video is the evidence of what went wrong.

run finds the project by walking up from the scenario file to the nearest demoflow.config.json. Without that file the command stops with no-project-config.

Note

Starting the app from devCommand is on develop and is not in the npm release 0.1.0. It arrives in the next npm release after 0.1.0. With 0.1.0, start your app yourself before demoflow run.

How it works

flowchart TD
  A["demoflow run file.demo.json"] --> B["Find project root<br/>(demoflow.config.json)"]
  B --> C["Load config, resolve home,<br/>validate scenario"]
  C --> D{"Inputs valid?"}
  D -- no --> X["Exit 2"]
  D -- yes --> E["Start app from devCommand<br/>+ ensure Chromium (in parallel)"]
  E --> F{"App answers readyUrl?"}
  F -- no --> G["result.json: readiness failed<br/>Exit 2"]
  F -- yes --> H["Run steps in Chromium<br/>record source.webm"]
  H --> I{"source.webm exists?"}
  I -- yes --> J["Render render/ffmpeg.mp4"]
  I -- no --> K["Settle result.json"]
  J --> K
  K --> L["Print summary or --json<br/>stop the app"]
Loading
  1. Find the project. run walks up from the scenario file to the nearest demoflow.config.json. That directory is the project root.
  2. Load the inputs. It loads and validates the project config, resolves the home directory, and loads and validates the scenario. Every css locator prints a warning on stderr. An invalid config or scenario stops the run here with exit code 2, before a browser is downloaded or the app is started.
  3. Start the app. If the config has a devCommand, run starts it. At the same time it checks that Chromium is installed and downloads it if it is missing. If readyUrl already answers, nothing is started. The app's output is kept and shown only if the start fails.
  4. App not ready. If the app never answers, run writes result.json itself. Readiness is failed, with the app's last output in the message, and every other stage is skipped. The command exits with 2.
  5. Execute. The engine checks readiness (allowed origins, base URL, secrets). It then launches Chromium (headless unless --headed), records the page and runs the steps in order. The first failing step stops the run.
  6. Render. If a source video was recorded, the renderer builds a render plan and writes render/ffmpeg.mp4. It does this whatever the verdict was, so a failed verification still produces a video.
  7. Settle. rendering and storage change from pending to skipped if nothing set them, the run status is derived again, and result.json is replaced.
  8. Report. run prints a short summary, or with --json one JSON object, and exits with a code that reflects the first failing stage. If run started the app, it stops the app.

Using it

Check a scenario without running it:

npx demoflow validate demoflow/customers.demo.json

It prints <file> is valid and exits 0. Warnings, such as a css locator, go to stderr. An invalid file exits 2 and lists each issue by path.

Run a scenario:

npx demoflow run demoflow/customers.demo.json

The summary lists every stage with its status, the path of each rendered video, and the run directory:

Run 20261018-200548-clfwzo: completed
  readiness     passed
  execution     passed
  verification  passed
  recording     passed
  rendering     passed
  storage       skipped
Video: <home>/runs/20261018-200548-clfwzo/render/ffmpeg.mp4
Run directory: <home>/runs/20261018-200548-clfwzo

Useful flags:

# Point the run at another server for this run only
npx demoflow run demoflow/login.demo.json --base-url http://localhost:4000

# Write the run under another home directory
npx demoflow run demoflow/login.demo.json --out ./demo-artifacts

# Watch the browser while it runs
npx demoflow run demoflow/login.demo.json --headed

# Machine-readable output: the final result.json plus "runDir"
npx demoflow run demoflow/login.demo.json --json

Scenarios that fill secrets read them from the environment only:

DEMO_PASSWORD=… npx demoflow run demoflow/login.demo.json

The full flag list is in CLI Reference.

Settings

Setting Where Effect on run
baseUrl demoflow.config.json Base for relative navigate paths. --base-url overrides it.
baseUrl the scenario Wins over both the config and --base-url when set.
allowedOrigins demoflow.config.json Origins the browser may visit. Defaults to the origin of baseUrl.
devCommand demoflow.config.json {command, args?, readyUrl, timeoutMs?}. Starts the app before the run.
render.* demoflow.config.json Output size, fps, idle compression, frame and background. See Rendering and Effects.
artifactsDir config files Where runs go. See Run Artifacts.

Base URL precedence. The scenario's own baseUrl is used first. Otherwise run uses --base-url if given, and then the config's baseUrl.

devCommand details:

  • The command runs without a shell, with the project root as the working directory.
  • run polls readyUrl every 250 ms. Any HTTP status below 500 counts as ready, including a redirect or a 404.
  • timeoutMs defaults to 60000.
  • When run started the app, it stops the whole process tree afterwards. On Linux and macOS it sends SIGTERM to the process group, then SIGKILL after a 5 s grace period. On Windows it uses taskkill /T /F.

See Project Configuration for every key.

Limits / what it never does

  • Secrets. Secrets come only from the process environment. If a valueFrom.env variable is missing or empty, readiness fails with missing-env NAME before any browser starts. See Secrets and Masking.
  • Origins. The browser may navigate only to allowedOrigins. Any other origin fails readiness with origin-not-allowed.
  • Stopping the app. run never stops an app it did not start. If readyUrl already answered, your server is left running.
  • Interrupts. Ctrl+C (SIGINT) and SIGTERM stop the app run started and exit with 130 or 143.
  • Storage. The storage stage is always skipped. There is no cloud upload; runs stay on disk.
  • Shared run directories. --run-id is internal (the MCP server uses it). It refuses a directory that already exists, so a run never overwrites another.

See also

Clone this wiki locally