DemoFlow

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": []
}
FieldMeaning
schemaVersionAlways 1.
nameRequired. Shown on the intro card.
descriptionOptional. Shown under the name on the intro card.
baseUrlOptional. Overrides the project config for this scenario.
device"desktop" (default) or "phone". See Record as a phone.
viewportThe browser size. Default 1920×1080, or 412×914 for a phone.
dataLists a repeat step runs over. See Repeat over data.
setupOptional. 1 to 200 steps that run before the recording starts. See Off-camera steps.
steps1 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 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.

KeyFinds
role (with optional name)an element by ARIA role and accessible name
labela form field by its label
testIdan element by its test id
textan element by its text
placeholdera field by its placeholder
cssa 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).

ActionWhat it doesFields
navigateOpens a page.exactly one of path (starts with a single /) or url
waitForWaits for an element.target, state (visible by default, or hidden)
clickClicks an element.target
fillTypes into a field.target, exactly one of value or valueFrom
selectPicks an option of a select.target, option
hoverMoves the pointer over an element.target
pressPresses a key or a chord, such as Enter or Control+a.key, optional target
scrollScrolls the page or a container.exactly one of to (top or bottom) or target; optional within
assertVisibleFails the run unless the element is visible.target
assertTextFails the run unless the element has the text.target, text, match (contains by default, or exact)
screenshotSaves a still.name (lowercase letters, digits and -)
waitForReadyWaits until your app signals it is ready. See Application SDK.name
markerMarks a scene or a caption in the video.title, kind (scene by default, or caption)
waitPauses on screen.ms (1 to 5000)
repeatRuns steps once per item of a list.See Repeat over data.
includeRuns 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" }
}

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" } }
      ]
    }
  ]
}

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 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" } }
  ]
}

demoflow record and @demoflow/playwright write plain steps; add include and setup to their scenarios by hand afterwards.