Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davidG97/qa-flow/llms.txt

Use this file to discover all available pages before exploring further.

QA Flow is designed to go from zero to running browser tests as fast as possible. With a single npx command the CLI pulls the official Docker image, starts the server, and opens the visual editor — no local installation, no configuration files, and no Playwright setup needed on your machine.

​
Prerequisites

Before you begin, make sure the following are available on your system:

Node.js 18+

Required to run the npx @davidg97/qa-flow launcher CLI. Download from nodejs.org.

Docker

The CLI launches QA Flow inside a Docker container. Install Docker Desktop from docs.docker.com/get-docker.

​
Launch Your First Test

1

Install and launch QA Flow

Run the following command in any terminal. The CLI will pull the davidg1997/qa-flow Docker image on first run and start the application on port 3001.
npx @davidg97/qa-flow
You will see the QA Flow banner, a Docker pull progress indicator, and then a confirmation that the server is running:
🚀 Starting on port 3001...
   Open: http://localhost:3001
   Login: admin@qaflow.com / admin123
The CLI automatically mounts three Docker volumes to persist your data across restarts:
VolumeContents
qa-flow-dataSQLite database (projects, flows, users)
qa-flow-screenshotsScreenshots captured during test runs
qa-flow-recordingsSession recordings
To use a different port, pass the -p / --port flag:
npx @davidg97/qa-flow --port 8080
2

Open the editor and log in

Navigate to http://localhost:3001 in your browser. You will be greeted by the QA Flow login screen.Use the default credentials to sign in:
FieldValue
Emailadmin@qaflow.com
Passwordadmin123
These credentials are intentionally simple for first-run evaluation. Change the admin password and set a strong JWT_SECRET environment variable (minimum 32 characters) before exposing QA Flow to any network other than localhost. See the Installation guide for details.
3

Create a new project

After logging in you will land on the projects dashboard. Click New Project, enter a name (for example, My First Project), and confirm. QA Flow will create the project and take you into the flow editor canvas.
4

Design your first test flow

The canvas starts empty. Build a test by dragging nodes from the left panel and connecting their ports:
  1. Drag a Start node onto the canvas. In its configuration panel, set the URL to the site you want to test (e.g. https://example.com) and choose a browser (Chromium is the default).
  2. Add action nodes — drag a Navigate node and set the path to /login, then a Type node for the email field, another Type node for the password field, and a Click node for the submit button.
  3. Add an assertion — drag an Assert Visible node and set its selector to .dashboard to confirm the login succeeded.
  4. Connect the nodes by dragging from the output handle of one node to the input handle of the next to form a chain.
Use the Visual Selector Picker (🎯) inside any node’s selector field to click elements directly in a live browser preview instead of typing CSS selectors by hand.
5

Run the test and watch it live

Click the ▶ Execute button in the toolbar. The execution panel slides open on the right and immediately begins streaming a live screencast of the Chromium browser as it works through your nodes.Each node in the canvas updates its status in real time:
  • 🟢 Green — step passed
  • 🔴 Red — step failed
  • 🟡 Yellow — step currently running
When the run finishes, click View Report to open the generated Playwright-style HTML report with per-step timings, screenshots, and pass/fail details.

​
Example: A Simple Login Test

Here is what a complete login test flow looks like as a node chain, using the configuration from the step above: 
[Start: https://example.com] → [Navigate: /login] → [Type: #email] → [Type: #password] → [Click: button[type="submit"]] → [Assert Visible: .dashboard]
The corresponding node configuration at a glance:
NodeKey SettingValue
StartURLhttps://example.com
NavigatePath/login
TypeSelector / Text#email / user@test.com
TypeSelector / Text#password / mypassword
ClickSelectorbutton[type="submit"]
Assert VisibleSelector.dashboard

​
CLI Reference

The npx @davidg97/qa-flow launcher supports a handful of flags for common tasks: 
# Start on a custom port
npx @davidg97/qa-flow --port 8080
npx @davidg97/qa-flow -p 8080

# Print the installed version and exit
npx @davidg97/qa-flow --version
npx @davidg97/qa-flow -v

# Show help and all available options
npx @davidg97/qa-flow --help
npx @davidg97/qa-flow -h

​
Next Steps

Installation Options

Run QA Flow via Docker directly or set up a full local development environment with pnpm.

Editor Guide

Deep-dive into every node type, the visual selector picker, device emulation, and flow management.

Build docs developers (and LLMs) love

Get started for freeTalk to us