Skip to content

Scenarios

Archi edited this page Oct 18, 2026 · 1 revision

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.

Overview

  • Scenario files live in the project under demoflow/ and end in .demo.json (demoflow/**/*.demo.json). The project root is the directory with demoflow.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"
    }
  ]
}

How it works

  1. The CLI reads the file and validates it against the scenario schema. Defaults are filled in (viewport, timeouts, match modes).
  2. Every { "css": … } locator produces a css-locator warning: the run continues, but the warning is reported.
  3. Before the browser starts, readiness checks run: every origin the scenario opens must be allowed, every relative navigate needs a base URL, and every valueFrom.env variable must be set.
  4. The steps run in order. The first failing step stops the run.
  5. 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"]
Loading

Using it

Check a file without running it:

npx demoflow validate demoflow/login.demo.json

Run it:

npx demoflow run demoflow/login.demo.json

Editors 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.

Top-level fields

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

Fields every step may carry

Field Default Notes
caption — At most 120 characters; shown as a lower-third caption in the video
timeoutMs 10000 Integer, 100–60000

Step actions

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

Keys for press

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, Alt and Meta, each at most once.
  • A bare letter or digit is accepted only with a modifier. Typing text is fill, not press.

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.

Locators

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.

Settings

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.

Limits / what it never does

  • 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 wait of at most 5 seconds.
  • A navigate to an origin outside allowedOrigins is refused before the browser starts.
  • Secret values are never written into the scenario; use valueFrom.env.

See also

Clone this wiki locally