Scenarios
A scenario is a JSON file, demoflow/**/*.demo.json, that lists the steps a
browser runs against your app. demoflow validate <file> checks it against the
schema and reports problems by path, such as steps[1].target.
{
"schemaVersion": 1,
"name": "Sign in",
"description": "A returning user signs in.",
"baseUrl": "http://localhost:3000",
"viewport": { "width": 1920, "height": 1080 },
"steps": []
}
| Field | Meaning |
|---|---|
schemaVersion | Always 1. |
name | Required. Shown on the intro card. |
description | Optional. Shown under the name on the intro card. |
baseUrl | Optional. Overrides the project config for this scenario. |
device | "desktop" (default) or "phone". See Record as a phone. |
viewport | The browser size. Default 1920×1080, or 412×914 for a phone. |
data | Lists a repeat step runs over. See Repeat over data. |
setup | Optional. 1 to 200 steps that run before the recording starts. See Off-camera steps. |
steps | 1 to 200 steps. |
Record as a phone
"device": "phone" records the scenario as a phone instead of a desktop:
{
"schemaVersion": 1,
"name": "Sign in on a phone",
"device": "phone",
"steps": [{ "action": "click", "target": { "role": "button", "name": "Sign in" } }]
}
- The viewport is 412×914 unless the scenario sets
viewport. - The browser is a touch device with a mobile user agent, and the page gets its
mobile
<meta name="viewport">. - The steps are the same;
clicktaps. - The video shows each tap as the click ring and draws no cursor arrow.
- The vertical and square crops follow targets up and down the page.
The page is recorded at its CSS size, so a 412-wide page is upscaled about 2.6× to fill a 1080-wide vertical or square frame. Those crops look softer than a desktop one; this is expected, not a bug. The landscape video stays sharp.
Locators
A step that acts on an element names it with a target, which holds exactly
one of these. They map one-to-one onto Playwright's locators, and there are no
coordinates.
| Key | Finds |
|---|---|
role (with optional name) | an element by ARIA role and accessible name |
label | a form field by its label |
testId | an element by its test id |
text | an element by its text |
placeholder | a field by its placeholder |
css | a CSS selector; accepted with a warning, prefer the others |
role, label, text and placeholder take "exact": true to match the
whole string instead of a part of it.
Steps
Every step has an action. Every step may also carry a caption, a
timeoutMs and "record": false (see Off-camera steps).
| Action | What it does | Fields |
|---|---|---|
navigate | Opens a page. | exactly one of path (starts with a single /) or url |
waitFor | Waits for an element. | target, state (visible by default, or hidden) |
click | Clicks an element. | target |
fill | Types into a field. | target, exactly one of value or valueFrom |
select | Picks an option of a select. | target, option |
hover | Moves the pointer over an element. | target |
press | Presses a key or a chord, such as Enter or Control+a. | key, optional target |
scroll | Scrolls the page or a container. | exactly one of to (top or bottom) or target; optional within |
assertVisible | Fails the run unless the element is visible. | target |
assertText | Fails the run unless the element has the text. | target, text, match (contains by default, or exact) |
screenshot | Saves a still. | name (lowercase letters, digits and -) |
waitForReady | Waits until your app signals it is ready. See Application SDK. | name |
marker | Marks a scene or a caption in the video. | title, kind (scene by default, or caption) |
wait | Pauses on screen. | ms (1 to 5000) |
repeat | Runs steps once per item of a list. | See Repeat over data. |
include | Runs the steps of a fragment. | fragment, optional with. See Fragments. |
caption
caption is up to 120 characters of text shown in the video while the step
runs.
{
"action": "click",
"target": { "role": "button", "name": "Publish" },
"caption": "Publish the post"
}
timeoutMs
timeoutMs is how long the step may wait for its element or condition before
the run fails: 100 to 60000 ms, 10000 by default.
Zoom
zoom moves the camera in on the step's target. true uses the renderer's
default strength; a number from 1 (no zoom) to 3 sets it. It is available on
steps that have a target, waitFor for a hidden element excepted, and on
press only when the press has a target. Nothing zooms unless a step asks.
{
"action": "click",
"target": { "role": "button", "name": "Publish" },
"zoom": 1.8
}
Scene markers
A marker with kind: "scene" starts a new scene. It gets a scene card in the
video unless cards are off. Your app can start scenes
and show captions itself; see Application SDK.
Secrets and masking
A secret never appears in a scenario. A fill takes its text from an
environment variable instead of value:
{
"action": "fill",
"target": { "label": "Password" },
"valueFrom": { "env": "DEMO_PASSWORD" }
}
- The value is read from the environment when the run starts. It does not touch disk or logs, and the timeline records a placeholder instead of it.
- A field filled this way is masked: the video blurs it from the
filluntil the field leaves the page. - To blur something that is not a filled field, such as an API key your app
shows, mark it in the page with
data-demoflow-mask. valueFromtakes a variable name (A-Z,0-9and_) and never a{{…}}placeholder, so data lists cannot carry secrets either.- If the variable is missing, the run fails at readiness, before the browser
starts, with exit code
2.
Repeat over data
A scenario can declare data lists and run a group of steps once per item.
{{post.text}} is the item's text field and {{index}} its 1-based position.
They work in every string of a step inside the repeat.
{
"schemaVersion": 1,
"name": "Post three updates",
"data": {
"posts": [
{ "text": "Hello" },
{ "text": "Shipping today" },
{ "text": "Thanks!" }
]
},
"steps": [
{ "action": "navigate", "path": "/feed" },
{
"action": "repeat",
"each": "posts",
"as": "post",
"caption": "Three posts",
"steps": [
{ "action": "click", "target": { "role": "button", "name": "Compose" } },
{ "action": "fill", "target": { "label": "Post" }, "value": "{{post.text}}" },
{ "action": "click", "target": { "role": "button", "name": "Publish" } }
]
}
]
}
- A list holds 1 to 100 items. An item is an object of strings, numbers and booleans.
eachnames the list;asnames the item and defaults toitem.indexis taken by{{index}}.- A
repeatholds 1 to 50 steps and norepeatof its own: loops are one level deep. - Its
captionis shown once, before the first iteration. - Every field a step uses must be in every item, and a URL, path or key must be valid once filled in.
demoflow validatereports a problem by step path, such assteps[1].steps[1].value, before anything runs. {{…}}is an error outside arepeat, except{{params.…}}in a fragment. Write\\{{in JSON for a literal{{.- The timeline and
result.jsoncount the expanded steps. A failure reads likestep 4 (repeat steps[1], iteration 3).
Fragments
A fragment is a list of steps that several scenarios share, such as signing
in. It lives in demoflow/fragments/<name>.json, or under the fragmentsDir
the project config names, and a scenario runs it with an
include step:
{
"schemaVersion": 1,
"description": "Signs the demo user in.",
"params": {
"next": { "description": "Where to go once signed in.", "default": "/" }
},
"steps": [
{ "action": "navigate", "path": "/login" },
{ "action": "fill", "target": { "label": "Email" }, "valueFrom": { "env": "DEMO_LOGIN_EMAIL" } },
{ "action": "fill", "target": { "label": "Password" }, "valueFrom": { "env": "DEMO_LOGIN_PASSWORD" } },
{ "action": "click", "target": { "role": "button", "name": "Sign in" } },
{ "action": "navigate", "path": "{{params.next}}" }
]
}
{
"action": "include",
"fragment": "sign-in",
"with": { "next": "/projects/demo-project" }
}
- The name is the file's path under the fragments directory, without
.json:sign-in, orauth/sign-inforauth/sign-in.json. A fragment file must be inside the project. paramsdeclares whatwithmay pass. A parameter without adefaultis required. Values are strings, numbers or booleans, and steps use them as{{params.<name>}}.- A fragment can include other fragments, up to 8 deep. It cannot hold a
repeat, and anincludecannot sit inside arepeat. valueFrom.envworks in a fragment as in a scenario, so secrets stay out of both.- The steps are inlined when the scenario is loaded: the timeline,
result.jsonand the run'sscenario.jsonshow them as ordinary steps. demoflow validatechecks every fragment a scenario includes. A missing fragment, an include cycle or a bad parameter is reported at theinclude, with the fragment file and step, such assteps[0].fragment: unknown fragment sign-in: no demoflow/fragments/sign-in.jsonorsteps[0]: in demoflow/fragments/sign-in.json steps[4].path: ….
The JSON schema for fragment files is fragment.schema.json in
@demoflow/core.
Off-camera steps
Steps the video should not show, such as signing in, run off camera. Put them
in the scenario's setup, or give the opening steps (or an include)
"record": false:
{
"schemaVersion": 1,
"name": "Create a project",
"setup": [
{ "action": "include", "fragment": "sign-in", "with": { "next": "/projects" } }
],
"steps": [
{ "action": "click", "target": { "role": "button", "name": "New project" } }
]
}
- Off-camera steps run first, in a browser context that records nothing. Its cookies and local storage carry over to the recorded context, which opens on the page the off-camera steps ended on. The video starts there, already signed in, on the first recorded step.
- Only the opening steps can be off camera:
setup, then any leading steps with"record": false. A"record": falsestep after a recorded one is an error, and at least one step must be recorded. recordgoes on arepeat, not on the steps inside it. Steps insetupare off camera already and take norecord.- The page is loaded again when recording starts, so state held only in memory or in session storage does not carry over.
- The timeline holds only the recorded steps, and its times and markers match
the video. Step numbers in
result.jsonand errors still count the off-camera steps,setupfirst. - A failed off-camera step fails the run before anything is recorded.
demoflow record and @demoflow/playwright write plain
steps; add include and setup to their scenarios by hand afterwards.