Repository navigation
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.
- 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.
- The CLI finds the project root by walking up from the current directory to
demoflow.config.json, and loads the config. - 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. - It makes sure Chromium is installed (downloading it on first use), then starts the app from
devCommandif the config has one and the app is not already answering. - 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. - Typing into one field folds into a single
fillwith the final value, rather than one step per keystroke. - 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. Acssfallback is shown as a warning in the panel. - 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.
- On a terminal the CLI asks
Run it now? [Y/n]; yes runs the new scenario asdemoflow runwould.
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]
npx demoflow record customers-searchThis writes demoflow/customers-search.demo.json. The name is turned into a file name: lowercase letters and digits, everything else becomes -.
| 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).
| 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.
| 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.
| 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 |
- 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.
- Scenarios — the format the recorder writes
-
Secrets and Masking — how
valueFrom.envis used at run time - Running Demos · CLI Reference · Project Configuration
-
Spec 79:
demoflow record· Spec 103: extra step while recording · Spec 91: thepressstep - ADR-0003: scenario format and project config
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference