Skip to content

Recording Scenarios

Archi edited this page Oct 18, 2026 · 2 revisions

Recording Scenarios

demoflow record writes a scenario for you while you use the app in a browser. You click, type and scroll; a small panel adds scenes, captions, waits and checks; the result is a normal demoflow/<name>.demo.json you can edit and run.

Note

record is on develop and arrives with the next npm release after 0.1.0. The published demoflow@0.1.0 has no record command.

Overview

  • The recorder opens a headed Chromium with two windows: the app, and a panel titled DemoFlow — recording.
  • What you do in the app becomes steps: clicks, typing, selects, scrolls, keys and typed navigations.
  • The panel adds what cannot be inferred from your gestures: scene and caption markers, waits, assertions and hovers.
  • Password fields are recorded as valueFrom.env; their value is never read.
  • When you stop, the scenario is validated and written, and the CLI offers to run it.

How it works

  1. The CLI finds the project root by walking up from the current directory to demoflow.config.json, and loads the config.
  2. It checks the name and the viewport, and refuses to overwrite an existing scenario file unless you pass --force — before any browser starts, so a name clash never costs a recording.
  3. It makes sure Chromium is installed (downloading it on first use), then starts the app from devCommand if the config has one and the app is not already answering.
  4. The app window opens on the project's baseUrl. A capture script in the page reports your gestures; each becomes a step, and the step list in the panel updates.
  5. Typing into one field folds into a single fill with the final value, rather than one step per keystroke.
  6. For each element, the recorder picks the first locator that is unique on the page, in this order: role + name, label, placeholder, testId, text, css. A css fallback is shown as a warning in the panel.
  7. Stop and save (or closing a window, or Ctrl+C in the terminal) ends the session. The steps are validated as a scenario and written; the file path is printed.
  8. On a terminal the CLI asks Run it now? [Y/n]; yes runs the new scenario as demoflow run would.
sequenceDiagram
  participant You
  participant App as App window
  participant Panel as Recording panel
  participant CLI as demoflow record
  You->>App: click, type, scroll, keys
  App->>CLI: captured gestures
  CLI->>Panel: updated step list
  You->>Panel: Scene, Caption, Wait, Pick, Secret next
  Panel->>CLI: extra steps
  You->>Panel: Stop and save
  CLI->>CLI: validate and write demoflow/name.demo.json
  CLI-->>You: Run it now? [Y/n]
Loading

Using it

npx demoflow record customers-search

This writes demoflow/customers-search.demo.json. The name is turned into a file name: lowercase letters and digits, everything else becomes -.

What becomes a step

You do Recorded as
Click a button, link, tab or other control click
Type into a text field fill with the final value
Type into a password field, or a field marked secret fill with valueFrom: { "env": … } — no value
Change a <select> select
Scroll to the top or bottom, or to an element scroll
Press Enter, Tab, Escape or an arrow key in a text field press on that field
Type a URL, or the first page load navigate (a path when the URL is under baseUrl)

Clicking a link does not add a separate navigate: the click already navigates. Keys are not recorded with a modifier held, inside a password or secret field, or Enter in a multi-line field (it types a newline).

The panel

Control Adds
Scene (with the text in the title field) a marker of kind scene
Caption (with the text in the title field) a marker of kind caption
Wait (with milliseconds, 1–5000) a wait step
Pick: visible, then click an element an assertVisible step
Pick: text, then click an element an assertText step with the element's text
Hover next, then click an element a hover step
Secret next, then type into a field a fill from the environment variable in the Secret variable field (default DEMO_PASSWORD)
↑ / ↓ / ✕ on a step move it up, move it down, delete it
Stop and save ends the recording

In Pick and Hover modes the click belongs to the recorder: the page never receives it.

Settings

Flag Default What it does
[name] recording Scenario name; the file is demoflow/<name>.demo.json
--force off Overwrite an existing scenario file
--no-run — Do not offer to run the scenario after saving it
--viewport <WxH> 1280x720 Browser viewport, written into the scenario

The recorder uses baseUrl, allowedOrigins and devCommand from demoflow.config.json (Project Configuration). A navigation to an origin that is not allowed is still recorded, with a warning that the run will refuse it.

Errors

Code Meaning Exit
invalid-name The name has no letters or digits 2
invalid-viewport Not of the form 1280x720 2
scenario-exists The file exists and --force was not given 2
nothing-recorded No steps; nothing was written 2
invalid-recording The steps do not form a valid scenario; nothing was written 2
app-not-ready The app did not start 3

Limits / what it never does

  • It never reads the value of a password field or of a field marked secret, and never records a key pressed inside one.
  • It does not overwrite an existing scenario without --force.
  • It does not record hovers by itself: use Hover next.
  • It records only the app window's main frame.
  • It does not ask to run the scenario when there is no terminal to answer.

See also

Clone this wiki locally