Repository navigation
Getting Started
This page takes you from nothing to a first demo video of your own web app: one config file, one scenario and one command. It works with the published demoflow@0.1.0.
You need:
-
Node.js 20 or later and
npx. -
A web app running locally, for example on
http://localhost:3000. - About 250 MB of disk for Chromium, which DemoFlow downloads once on first use.
FFmpeg is optional: DemoFlow uses ffmpeg from your PATH when it has one and a bundled copy otherwise. Details are in Installing.
-
demoflow.config.jsonat your project root tells DemoFlow where the app is. - A scenario in
demoflow/<name>.demo.jsonlists the steps: navigate, click, fill, assert. -
demoflow runruns the steps in Chromium, checks the assertions and records the page. - The renderer turns the recording into
render/ffmpeg.mp4inside a run directory.
sequenceDiagram
participant You
participant CLI as demoflow run
participant App as Your app
participant Out as Run directory
You->>CLI: npx demoflow run demoflow/first.demo.json
CLI->>App: drive Chromium through the steps
App-->>CLI: pages, assertions pass
CLI->>Out: source.webm, timeline.json, result.json
CLI->>Out: render/ffmpeg.mp4
CLI-->>You: summary and exit code 0
1. Point DemoFlow at your app. Create demoflow.config.json at the project root:
{
"baseUrl": "http://localhost:3000"
}2. Write a scenario. Create demoflow/first.demo.json. Replace the locators with ones from your app — a role and an accessible name are the most robust:
{
"schemaVersion": 1,
"name": "Open the settings",
"description": "Go to the home page and open the settings.",
"viewport": { "width": 1280, "height": 720 },
"steps": [
{ "action": "navigate", "path": "/" },
{
"action": "click",
"target": { "role": "link", "name": "Settings" },
"caption": "Open the settings"
},
{ "action": "assertVisible", "target": { "role": "heading", "name": "Settings" } }
]
}3. Check it without a browser:
npx demoflow validate demoflow/first.demo.json4. Start your app, then run the scenario:
npx demoflow run demoflow/first.demo.jsonThe first run downloads Chromium. When it finishes, the summary names the run directory; the video is render/ffmpeg.mp4 inside it. By default run directories live in the OS data directory (on Linux ~/.local/share/demoflow/runs/); Run Artifacts has every location and how to change it.
Tip
Add --headed to watch the browser, or --json to get the result as one JSON object for scripts.
- Let
runstart the app for you withdevCommand— see Project Configuration (ondevelop, next npm release). - Record a scenario by clicking instead of writing JSON — Recording Scenarios (on
develop, next npm release). - Type a password without putting it in the file — Secrets and Masking.
- Ask Claude Code for a demo — MCP Server.
- It does not start your app on
0.1.0; start it yourself first. - It only visits the origins in
allowedOrigins(by default the origin ofbaseUrl). See Security and Access. - It never uploads anything: the video stays on your disk.
Note
Run npx demoflow from your own project. Inside the DemoFlow monorepo itself, npx demoflow resolves to the private workspace package instead of the npm one (#105).
- Scenarios — every step and locator
- Running Demos — flags, base URL, exit behaviour
- CLI Reference
- FAQ
- Spec 5 — CLI run, ADR-0003 — scenario format and project config
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