Skip to content

Getting Started

Archi edited this page Oct 18, 2026 · 1 revision

Getting Started

This page takes you from nothing to a first demo video of your own web app: one config file, one scenario and one command. It works with the published demoflow@0.1.0.

Overview

You need:

  • Node.js 20 or later and npx.
  • A web app running locally, for example on http://localhost:3000.
  • About 250 MB of disk for Chromium, which DemoFlow downloads once on first use.

FFmpeg is optional: DemoFlow uses ffmpeg from your PATH when it has one and a bundled copy otherwise. Details are in Installing.

How it works

  1. demoflow.config.json at your project root tells DemoFlow where the app is.
  2. A scenario in demoflow/<name>.demo.json lists the steps: navigate, click, fill, assert.
  3. demoflow run runs the steps in Chromium, checks the assertions and records the page.
  4. The renderer turns the recording into render/ffmpeg.mp4 inside a run directory.
sequenceDiagram
  participant You
  participant CLI as demoflow run
  participant App as Your app
  participant Out as Run directory
  You->>CLI: npx demoflow run demoflow/first.demo.json
  CLI->>App: drive Chromium through the steps
  App-->>CLI: pages, assertions pass
  CLI->>Out: source.webm, timeline.json, result.json
  CLI->>Out: render/ffmpeg.mp4
  CLI-->>You: summary and exit code 0
Loading

Using it

1. Point DemoFlow at your app. Create demoflow.config.json at the project root:

{
  "baseUrl": "http://localhost:3000"
}

2. Write a scenario. Create demoflow/first.demo.json. Replace the locators with ones from your app — a role and an accessible name are the most robust:

{
  "schemaVersion": 1,
  "name": "Open the settings",
  "description": "Go to the home page and open the settings.",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    { "action": "navigate", "path": "/" },
    {
      "action": "click",
      "target": { "role": "link", "name": "Settings" },
      "caption": "Open the settings"
    },
    { "action": "assertVisible", "target": { "role": "heading", "name": "Settings" } }
  ]
}

3. Check it without a browser:

npx demoflow validate demoflow/first.demo.json

4. Start your app, then run the scenario:

npx demoflow run demoflow/first.demo.json

The first run downloads Chromium. When it finishes, the summary names the run directory; the video is render/ffmpeg.mp4 inside it. By default run directories live in the OS data directory (on Linux ~/.local/share/demoflow/runs/); Run Artifacts has every location and how to change it.

Tip

Add --headed to watch the browser, or --json to get the result as one JSON object for scripts.

Next steps

Limits / what it never does

  • It does not start your app on 0.1.0; start it yourself first.
  • It only visits the origins in allowedOrigins (by default the origin of baseUrl). See Security and Access.
  • It never uploads anything: the video stays on your disk.

Note

Run npx demoflow from your own project. Inside the DemoFlow monorepo itself, npx demoflow resolves to the private workspace package instead of the npm one (#105).

See also

Clone this wiki locally