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, a hold 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
}
hold
hold keeps the page on screen after the step, for 100 to 10000 ms. The run
waits that long once the step is done, and the video plays the whole hold at
real speed: the idle trim never shortens it. A step that
fails does not hold. hold is refused on an off-camera step
("record": false).
Use hold, not wait, to show something. A wait on a still page is idle
time, and the render shortens it to render.idle.compressToMs (400 ms by
default).
Show the result
Assert the result, zoom in on it and hold it. An assertion with zoom keeps the
camera on the element it found through its hold, and outlines it:
{
"action": "assertVisible",
"target": { "text": "My first post" },
"zoom": true,
"hold": 2000
}
The outline is drawn where the element was when the assertion passed, so hold an element that has stopped moving.
Every successful video also ends on its last frame for
render.endHoldMs (2500 ms by default), after the last
step's own hold.
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.