Flowprint

Self-contained Playwright recording, splitting, and test-management dashboard. Record sessions in a browser, let Claude split them into structured tests, promote into a catalog, and run them — all from a local web UI.

What you get: a local dashboard that handles the full test lifecycle — record, AI-split, review, promote, and run — without any cloud dependency. Your tests and sessions stay on your machine.

Requirements

• Node.js v22.14.0 or higher (download here)
• An Anthropic API key (get one here)

There are three ways to run Flowprint:

1. From npm — the easiest way, for anyone who just wants to use Flowprint.
2. With the tarball — for offline or private distribution.
3. In dev mode — for contributors working on Flowprint itself (this repo).

Running Flowprint from npm

1. Initialize a workspace

npm init @lil_devs/flowprint flowprint-tests

Replace flowprint-tests with whatever you'd like to name your project folder (or omit it to initialize the current directory). This will:

• Create the folder if it doesn't exist
• Write a package.json with the flowprint run script
• Install Flowprint from npm
• Scaffold the workspace (playwright.config.ts, tests/, playground/, flowprint.config.json)

No browser is opened at this step — the command is init only.

If the directory is already initialized, the command validates the existing files and exits without reinstalling.

2. Launch the dashboard

cd flowprint-tests
npm run flowprint

This validates the workspace, starts the server, and opens your browser directly at the Flowprint dashboard (not the landing page). A free port is picked automatically if 3005 is in use.

You can also target a different initialized folder without changing directories:

npm run flowprint -- /absolute/path/to/flowprint-tests

3. Add your Anthropic API key

If no API key is configured when the dashboard opens, the Settings → API key & Model panel opens automatically. Paste your key and click Save AI settings. You can close the panel at any time and add the key later. The key persists across restarts.

4. (Optional) Point at a different workspace

Go to Settings → Workspace and enter the absolute path to another folder. The dashboard will scaffold it if empty and switch immediately.

Running Flowprint with the tarball

For offline installs or private distribution where you can't rely on the npm registry.

1. Save the installer

Save create-flowprint-0.1.1.tgz to a convenient folder (e.g. ~/Documents).

2. Initialize and install in one command

cd ~/Documents
npx ./create-flowprint-0.1.1.tgz flowprint-tests

Replace flowprint-tests with whatever you'd like to name the install folder. This installs Flowprint from the bundled tarball — no internet connection required after download.

3. Launch the dashboard

cd ~/Documents/flowprint-tests
npm run flowprint

Running Flowprint in dev mode

For contributors working on this repo.

Quick start

From the repo root:

| Step | Command | Notes | |------|---------|-------| | 1 | npm install | Includes Express, Vite/React build, @playwright/test. | | 2 | npm run playwright:install-chromium | Required for Record / Run. Use playwright:install for all browsers. | | 3 | npm run dashboard:build | Builds UI into app/dashboard/public/ (required for a non-blank UI on port 3005). | | 4 | npm run dashboard | Same as node app/server.js. Default http://localhost:3005 (DASHBOARD_PORT to change). |

One-liner:

npm install && npm run playwright:install-chromium && npm run dashboard:build && npm run dashboard

Hot reload (UI development)

npm run dashboard:dev

Vite serves the UI at http://localhost:5173 and proxies /api to the server on 3005. Re-run npm run dashboard:build before relying on the static app/dashboard/public/ bundle.

Two-terminal alternative: npm run dashboard + npm run dashboard:client.

Workspace selection

The server needs a resolved root for Playwright config, sessions, and tests.

| Mode | How to point it | |------|-----------------| | External (preferred) | AUTOMATION_DIR env var or --workspace <path> flag. Parent path is OK — resolves to nested automation/ when config exists there. Hint file: ~/.flowprint/automation-dir.txt. | | Legacy app repo | --root <path> or WORKSPACE_ROOT — repo containing an automation/ subtree. Hint file: ~/.flowprint/workspace-root.txt. |

With neither set the workspace defaults to this devkit directory.

To scaffold a new external workspace from AUTOMATION_DIR in .env:

npm run init

Useful environment variables

| Variable | Role | |----------|------| | AUTOMATION_DIR | External workspace (parent or inner …/automation). | | WORKSPACE_ROOT / AUTOMATION_WORKSPACE | Legacy app repo root. | | DASHBOARD_PORT | Server port (default 3005, auto-falls-through if busy). | | DASHBOARD_NO_OPEN | Set to 1 to skip auto-opening the browser. | | FLOWPRINT_OPEN_PATH | URL path to open in the browser on startup (default /app). | | DASHBOARD_CODEGEN_URL / PLAYWRIGHT_BASE_URL | Record / codegen default URL. | | ANTHROPIC_API_KEY | Claude Process / merge agents. | | AUTOMATION_PROJECT_CONTEXT | Optional path to PROJECT_CONTEXT.md. |

More variables and details: OVERVIEW.md.

Scripts

| Script | Purpose | |--------|---------| | npm run flowprint | Validate workspace + start server, opens browser at /app (dashboard). | | npm run dashboard | Production server (serves the pre-built UI from app/dashboard/public/), opens at /app. | | npm run dashboard:client | Vite dev server only (5173, proxies /api to 3005). | | npm run dashboard:dev | Server + Vite together with hot reload. | | npm run dashboard:build | Vite production build → app/dashboard/public/. | | npm run init | Scaffold an external workspace from AUTOMATION_DIR in .env. | | npm run init-workspace | Scaffold with explicit --root / --workspace. | | npm run playwright:install / :install-chromium / :install-deps | Browsers / Linux deps. | | npm run pack:dist | Build the single-file release tarball in dist/ (see Building a release tarball). | | npm run version:bump <x.y.z\|patch\|minor\|major> | Set both packages to the same new version in one step. | | npm run publish:npm | Run preflight checks, then publish @lil_devs/flowprint and @lil_devs/create-flowprint to the npm registry. |

Releasing

For the full release process — version bumping, npm publish, tarball builds, deprecation, smoke testing, and known gotchas — see RELEASING.md.

Troubleshooting

• Cannot find module '@playwright/test' when running tests — Restart npm run flowprint. Flowprint sets NODE_PATH so a workspace in a sibling folder can still resolve @playwright/test from the install folder.
• API key didn't save — Try saving again via Settings → API key & Model. The key is stored in the devkit .env and mirrored into flowprint.config.json in your workspace.
• Port 3005 already in use — Flowprint automatically tries 3006, 3007, etc. and prints the actual URL on startup.
• Workspace not initialized error — Run npm init @lil_devs/flowprint <dir> to scaffold the workspace before running npm run flowprint.
• Init runs an old/unexpected command — npm init can reuse a stale create-flowprint from the npx cache. Force the latest scaffolder with npm init @lil_devs/flowprint@latest <dir>, or clear the cache with npx clear-npx-cache (or rm -rf "$(npm config get cache)/_npx").
• Doing it the long way — mkdir flowprint-tests && cd flowprint-tests && npm init -y && npm install @lil_devs/flowprint && npm run flowprint.
• Linux: Chromium missing host deps — sudo npx playwright install-deps (Playwright host deps).

License

This project is licensed under the MIT License.