Repository navigation
Scenarios
A scenario is a JSON file that describes one demo, step by step: where to go, what to click and type, and what must be true at the end. DemoFlow runs it in Chromium, records it and renders the video from it.
- Scenario files live in the project under
demoflow/and end in.demo.json(demoflow/**/*.demo.json). The project root is the directory withdemoflow.config.json— see Project Configuration. - The format is plain JSON validated by a strict schema: unknown keys are errors, not ignored.
- Elements are found with structured locators (role, label, text, …), never with screen coordinates.
- Secrets never appear in a scenario. A password is read from an environment variable at run time — see Secrets and Masking.
- You can write a scenario by hand, or record one by using the app: see Recording Scenarios.
A minimal example, the sign-in scenario of the repository's fixture app (apps/fixture/demoflow/login.demo.json):
{
"schemaVersion": 1,
"name": "Sign in",
"viewport": { "width": 1280, "height": 720 },
"steps": [
{ "action": "navigate", "path": "/login" },
{ "action": "fill", "target": { "label": "Email" }, "value": "ada@example.com" },
{ "action": "fill", "target": { "label": "Password" }, "valueFrom": { "env": "FIXTURE_PASSWORD" } },
{ "action": "click", "target": { "role": "button", "name": "Sign in" } },
{
"action": "assertText",
"target": { "role": "heading", "name": "Welcome" },
"text": "Welcome, ada@example.com"
}
]
}- The CLI reads the file and validates it against the scenario schema. Defaults are filled in (viewport, timeouts, match modes).
- Every
{ "css": … }locator produces acss-locatorwarning: the run continues, but the warning is reported. - Before the browser starts, readiness checks run: every origin the scenario opens must be allowed, every relative
navigateneeds a base URL, and everyvalueFrom.envvariable must be set. - The steps run in order. The first failing step stops the run.
- Each step becomes an event in
timeline.json, which the renderer turns into cursor moves, zooms, captions and masks.
flowchart LR
F["demoflow/name.demo.json"] --> V["Schema check<br/>+ css warnings"]
V --> R["Readiness:<br/>origins, base URL, env"]
R --> S["Steps run in Chromium"]
S --> T["timeline.json"]
T --> Vid["Rendered video"]
Check a file without running it:
npx demoflow validate demoflow/login.demo.jsonRun it:
npx demoflow run demoflow/login.demo.jsonEditors can validate as you type: point $schema at the generated JSON Schema, packages/core/schemas/scenario.schema.json. The $schema key is accepted by the parser.
| Field | Required | Default | Notes |
|---|---|---|---|
$schema |
no | — | Path or URL of the JSON Schema, for editors |
schemaVersion |
yes | — | Must be 1
|
name |
yes | — | Non-empty; the name shown for the demo |
description |
no | — | Free text |
browser |
no | chromium |
The only value accepted |
baseUrl |
no | — | Absolute http/https URL. When set, it wins over the project's baseUrl and --base-url
|
viewport |
no | { "width": 1920, "height": 1080 } |
Positive integers |
steps |
yes | — | 1 to 200 steps |
| Field | Default | Notes |
|---|---|---|
caption |
— | At most 120 characters; shown as a lower-third caption in the video |
timeoutMs |
10000 |
Integer, 100–60000 |
| Action | Fields | What it does |
|---|---|---|
navigate |
exactly one of path or url
|
Opens a page. path must start with a single / and is resolved against the base URL; url is an absolute http/https URL |
waitFor |
target, state (visible | hidden, default visible) |
Waits until the element is in that state |
click |
target |
Clicks the element |
fill |
target, exactly one of value or valueFrom: { "env": "NAME" }
|
Types into a field. NAME must match ^[A-Z_][A-Z0-9_]*$
|
select |
target, option
|
Chooses an option in a select |
hover |
target |
Moves the pointer over the element |
press |
key, optional target
|
Sends a key or chord. Without a target, the key goes to the focused element |
scroll |
exactly one of to (top | bottom) or target; optional within
|
Scrolls the page, or the container given by within
|
assertVisible |
target |
Fails unless the element is visible |
assertText |
target, text, match (exact | contains, default contains) |
Fails unless the element's text matches |
screenshot |
name (lowercase letters, digits and -) |
Saves a screenshot of the page |
marker |
title, kind (scene | caption, default scene) |
Marks a point in the timeline; a caption marker shows a caption |
wait |
ms (1–5000) |
Pauses |
key is one of Enter, Tab, Escape, Backspace, Delete, Space, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, F1–F12, or a chord joined with +, such as Control+a or Meta+k.
- Modifiers are
Control,Shift,AltandMeta, each at most once. - A bare letter or digit is accepted only with a modifier. Typing text is
fill, notpress.
Note
press is on develop and arrives with the next npm release after 0.1.0. The published demoflow@0.1.0 does not accept it.
A target (and within) is exactly one of these shapes. They map one to one onto Playwright's locators.
| Locator | Example | Notes |
|---|---|---|
| role | { "role": "button", "name": "Sign in" } |
role is an ARIA role; name and exact are optional |
| label | { "label": "Email" } |
Optional exact
|
| placeholder | { "placeholder": "Search" } |
Optional exact
|
| testId | { "testId": "save" } |
— |
| text | { "text": "Customers" } |
Optional exact
|
| css | { "css": ".toolbar > button" } |
Accepted, with a css-locator warning |
Prefer role + name: it survives markup changes and reads well. A CSS selector breaks when the markup changes.
Run-wide settings — base URL, allowed origins, the dev server command, render size — live in demoflow.config.json, not in the scenario. See Project Configuration.
- No coordinates: a step always targets an element through a locator.
- No free-text typing through
press; only the listed keys and chords. - Only Chromium.
- At most 200 steps, and a
waitof at most 5 seconds. - A
navigateto an origin outsideallowedOriginsis refused before the browser starts. - Secret values are never written into the scenario; use
valueFrom.env.
- Recording Scenarios — author a scenario by clicking
-
Secrets and Masking —
valueFrom.envand blurred fields - How a Demo Flows — what happens to a scenario during a run
- Running Demos · CLI Reference · Project Configuration
- ADR-0003: scenario format and project config
-
Spec 1: core contracts · Spec 91: the
pressstep
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