From zero to localhost:7823.

Three steps: get your auth key, install the agent, log in and launch the web UI. The browser opens at localhost:7823 and you're in.

1. Sign up and get your auth key

Create an account at qaclan.com and copy your auth key from Settings → Auth Key.

2. Install the agent

Linux / macOS

$ curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

Supports Linux (amd64) and macOS (arm64).

Windows (amd64 / arm64)

QAClan ships a standalone .exe — no Python required. Pick the build for your CPU:

• Intel/AMD 64-bit → qaclan-windows-amd64.exe
• ARM64 (Surface Pro X, Copilot+ PCs) → qaclan-windows-arm64.exe

Or grab the latest from the releases page. After downloading, open PowerShell in the folder containing the .exe and run the commands below from there.

> npm install -g [email protected]
> playwright install chromium

3. Log in and launch the web UI

Linux / macOS

$ qaclan login --key <your_auth_key> && qaclan serve

Windows (PowerShell)

> .\qaclan-windows-amd64.exe login --key <your_auth_key>
> .\qaclan-windows-amd64.exe serve

Use qaclan-windows-arm64.exe on ARM64 devices.

The browser opens at http://localhost:7823 — start managing your Playwright tests locally.

Seven nouns, one verb.

QAClan's vocabulary is small. Learn these seven entities and you've learned the whole tool.

Project

The top-level workspace, usually one per product. Every other entity belongs to a project. The agent always has exactly one active project — switch it from the sidebar dropdown.

Feature

A group of scripts by app area — "Authentication", "Checkout". Each feature has a channel: web (Playwright browser flows) or api (HTTP contract checks). These docs cover web.

Script

A single Python file executing one logical user flow. Its source is either RECORDED (captured via Playwright codegen) or WEB_CREATED (written in the UI editor). Scripts may declare a start_url and a list of var_keys like {{EMAIL}} to be substituted at run time.

Suite & Suite Item

A suite is an ordered list of suite items, each pointing at a script. Same script can appear in many suites — it's always one file on disk. Reorder items by dragging in the UI.

Suite Run & Script Run

A suite run is one execution of a suite. Each script inside gets a script run with status (PASSED, FAILED, SKIPPED), duration, console errors, network failures, screenshots, and a step-by-step breakdown.

Environment

A named bag of KEY=value pairs (some marked is_secret). Applied at run time — injected into the script subprocess as env vars, and used to resolve {{KEY}} template placeholders inside script files.

Install.

One pip install, one Playwright browser download. The agent ships the CLI, the web UI, and the runner.

Requirements

• OS Linux (amd64), macOS (arm64), or Windows (amd64 / arm64)
• Disk ~400 MB for Playwright browsers
• Port 7823 free for the local web UI
• Node.js LTS — Windows only, for system-installed Playwright

Install the binary

This is the default, recommended path. No Python required.

Linux / macOS

$ curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

The installer drops the qaclan binary into a directory on your PATH and bundles the Playwright browsers it needs. Supports Linux (amd64) and macOS (arm64).

Windows

Download the standalone .exe that matches your CPU:

• Intel/AMD 64-bit → qaclan-windows-amd64.exe
• ARM64 (Surface Pro X, Copilot+ PCs) → qaclan-windows-arm64.exe

Or grab the latest from the releases page.

The Windows binary uses your system-installed Playwright instead of bundling it. Install Node.js (LTS) from nodejs.org, then in PowerShell:

> npm install -g [email protected]
> playwright install chromium

Verify

$ qaclan status
✓ signed out
✓ data dir  ~/.qaclan
✓ no active project

Run from source (development)

Only needed if you're hacking on the agent itself.

• Python 3.10 or newer

$ git clone https://github.com/qaclan/agent.git && cd agent
$ python3 -m venv env && source env/bin/activate
$ pip install -r requirements.txt
$ playwright install chromium firefox webkit
$ python qaclan.py serve --port 7823

Local data paths

Everything the agent needs sits under ~/.qaclan/:

Upgrade

Linux / macOS — re-run the installer; it replaces the existing qaclan binary in place:

$ curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

Windows — download the latest .exe from the releases page and overwrite the existing file.

Uninstall

The agent ships a cleanup command — it removes ~/.qaclan/ entirely. Pass -y to skip the prompt.

$ qaclan uninstall
? Delete ~/.qaclan (14 projects, 482 scripts)? (y/N)

Authentication.

One auth key per user, tied to your qaclan.com account. Grab it from the dashboard, pass it to qaclan login, you're done.

1. Sign up and get your auth key

Go to qaclan.com and Sign in with Google — Google OAuth is the only sign-in method. An auth key is generated automatically on first sign-up.

Open Settings → Auth Key to view and copy it. The key looks like qc_… (a qc_ prefix followed by a 32-byte url-safe random token).

2. Log in from the agent

$ qaclan login --key <your_auth_key>

On Windows, substitute the binary you downloaded:

> .\qaclan-windows-amd64.exe login --key <your_auth_key>

The agent validates the key against the server, then stores it in ~/.qaclan/config.json (or %USERPROFILE%\.qaclan\config.json on Windows).

From the web UI

If you start qaclan serve without being logged in, the first screen prompts for your auth key. Paste it, click Save, and you're in.

Regenerate your key

If a key leaks, open Settings → Auth Key → Regenerate Key on qaclan.com. This invalidates the old key immediately — any agent still using it will need to qaclan login --key <new_key> before its next call succeeds.

Log out

$ qaclan logout

Removes the key from config.json. Subsequent commands (except login, logout, serve) will error until you log in again.

The agent web UI.

Everything you do day-to-day happens here. Start it with qaclan serve, open localhost:7823, and you land on the Scripts page of the active project.

Layout

• Left sidebar — six navigation items in a fixed order.
• Top bar — project switcher (top-right), Push, Pull, and theme toggle.
• Main area — the active page.

Sidebar navigation

The sidebar shows six items, in this order:

1. Environment — named variable sets for running tests
2. Features — grouped under Testing
3. Scripts — default landing page
4. Suites
5. Runs
6. Settings — pinned to the bottom

Top bar

The top bar carries four global controls:

• Project switcher (top-right) — dropdown listing every local project. Click to switch the active project or to create a new one. Everything in the sidebar pages filters to the selection.
• Push (↑) — manually push pending local changes to the cloud. Normally happens in the background; this button forces it.
• Pull (↓) — fetch workspace and run history from the cloud.
• Theme toggle (☀ / ☾) — flip between dark and light. Preference is saved to localStorage under qaclan-theme.

Pages at a glance

Projects.

A project is your workspace — usually one per product. The agent always operates on the active project.

Create

Open the project switcher in the top-right of the top bar → + New project. Enter a name. The new project is created and immediately made active.

Switch

Click the project switcher in the top bar → pick a project. Everything in the UI — scripts, features, suites, runs, environment — filters to that project.

Delete

Open the project in the switcher, then use the Delete project option. Confirm the count of features, scripts, suites, and runs you're about to remove — or use the CLI:

$ qaclan project delete <project_id>

Project IDs

Every project has a local ID prefixed proj_ and, once synced, a cloud_id (UUID). You'll see the local ID in the Settings page and in run URLs.

Features.

Features group scripts by app area. A feature has a channel — web for Playwright browser flows, api for HTTP contract checks.

Create

Sidebar → Features → + New feature. Choose a name and a channel (web / api). That's it.

Edit

Click a feature's row to rename it. Channel is locked after creation — you can't flip a web feature to api without recreating.

Delete

Hover a row → trash icon → confirm. The agent tells you how many scripts you're about to remove with it.

Scripts.

A script is a single Python file that drives one logical flow. Record it with Playwright codegen, or write it from scratch in the in-browser editor.

Record a script

Sidebar → Scripts → + Record. In the dialog:

• Name — what you'll see in the list.
• Feature — which feature it belongs to.
• Start URL — where the browser opens. Either paste a literal URL, or reference a variable like {{BASE_URL}} that will resolve at run time.

Hit Start recording. A Chromium window opens to your start URL and Playwright codegen captures every click, fill, and navigation. Close the window when you're done — the agent saves the generated .py and tags the script source: RECORDED.

Write one manually

Sidebar → Scripts → + New script. Name, feature, confirm. The in-browser editor opens with a template — same editor used for edits.

The editor

QAClan ships CodeMirror 6 with the Python language pack and the oneDark theme. Shortcut keys match what you'd expect:

• ⌘S / Ctrl-S save
• ⌘/ toggle line comment
• ⌘F find / replace

Template variables

Anywhere in the script — or in the start URL — you can write {{KEY}}. At run time the agent substitutes from the active environment. Every key you reference is recorded on the script's var_keys list so the UI can warn you if an environment is missing one.

Script template (recorded scripts look similar)

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()   # agent rewrites this at runtime
    page    = context.new_page()

    page.goto("{{BASE_URL}}/login")
    page.get_by_label("Email").fill("{{EMAIL}}")
    page.get_by_label("Password").fill("{{PASSWORD}}")
    page.get_by_role("button", name="Sign in").click()
    page.wait_for_url("**/dashboard")

    browser.close()

Runtime patching

Before each run the agent patches your script in memory — you don't write this boilerplate yourself:

• Storage state — browser.new_context() becomes browser.new_context(storage_state=QACLAN_STORAGE_STATE if set and exists else None). Before the script exits, context state is saved back to the same path. That's how scripts in a suite share a browser session.
• Wait for network-idle — after every page.goto(...) and .click(...) the agent inserts page.wait_for_load_state("networkidle"). No more flaky "element not attached" failures.
• Template resolution — {{KEY}} placeholders become literal strings from the active environment.

Edit & delete

Click any script to open the editor. Rename inline. Delete from the row menu. Every change is written immediately to ~/.qaclan/scripts/<name>.py.

Suites.

A suite is an ordered list of scripts you run as a unit. Scripts share browser session state through the suite.

Create

Sidebar → Suites → + New suite. Name it. Pick a channel (web / api — matches the scripts you'll add).

Add scripts

Open the suite → + Add scripts. Pick from the list of scripts in the active project. Add as many as you want; they appear in the order you added them.

Reorder

Drag a row by its handle to reorder. Order matters — scripts share session state in sequence, so "sign-in" must come before "view-dashboard".

Shared browser session

Every script in a suite is given the same QACLAN_STORAGE_STATE file path. Thanks to runtime patching (see Scripts), the first script's cookies, localStorage, and auth headers are picked up by the second, the second by the third, and so on.

One script, many suites

The same script can live in any number of suites — add it to a "Smoke" suite and a "Full Regression" suite simultaneously. The script exists in one place on disk and each suite just holds a reference (si_… suite item) with its own order index.

Remove / reorder items

Row menu → Remove from suite. The script itself is untouched.

Running tests.

Open any suite, hit Run. The run dialog asks for browser, resolution, headless mode, stop-on-fail, and environment.

Run options

Live status

Once started, the Runs page streams status in real time. Each script row flips from QUEUED → RUNNING → PASSED or FAILED, and the header rollup updates: total / passed / failed / skipped.

What gets captured

For each script run the agent stores:

• Status — PASSED, FAILED, or SKIPPED (when stop_on_fail ended the suite early)
• Duration — in milliseconds
• Console errors — any console.error() from the page
• Network failures — failed requests, 4xx/5xx responses
• Error message — stderr from the Python subprocess on failure
• Screenshot — final page state, on failure
• Step runs — action-by-action timeline (step_… entries) with per-step duration and error

Replays & artifacts

Clicking into a script run shows the console log, network log, step timeline, and screenshot. All artifacts live under ~/.qaclan/runs/<run_id>/ — bring-your-own-viewer if you prefer.

Environments.

Named bags of variables. Apply one at run time and its values are injected into the script subprocess and used to resolve {{KEY}} placeholders. The sidebar item is labelled Environment (singular).

Create

Sidebar → Environment → + New environment. Name it (dev, staging, prod — whatever maps to your deployment).

Set variables

Click into an environment → + Add variable. Each variable has three fields:

• Key — referenced as {{KEY}} in scripts and start URLs, and available as os.environ["KEY"] at runtime.
• Value — the literal string.
• Secret — toggle to mark is_secret. Secret values are masked in the UI and redacted from logs.

Copy an environment

Row menu → Duplicate (hits POST /api/envs/:name/copy). Convenient for "make a staging copy of dev and change two values".

Use in a run

When you open the run dialog on any suite, pick the environment from the dropdown. Every variable is injected; every {{KEY}} is resolved. If a referenced key is missing, the run fails fast with a clear error before any browser launches.

Cloud sync.

Sync is best-effort. Changes are queued locally and a background worker pushes them to the server. Failures never block the agent — they retry with backoff.

Push and Pull

Two buttons in the top bar control sync manually:

• Push (↑) — re-enqueues every entity in the active project (or all projects if none is active) and flushes the queue. Useful after a long offline stretch.
• Pull (↓) — mirrors the cloud workspace down onto this laptop.

You don't normally need either — the background worker keeps things in sync as you work. The buttons are for "I want this to happen now".

What syncs

Sync is full-fidelity. Everything the agent tracks is pushed, including script file contents:

• Projects
• Features — name, channel (web / api)
• Scripts — metadata and the .py file contents (sent as plain-text file_content)
• Suites and suite items — with order index
• Environments and env vars — including values (secrets included)
• Suite runs — status, counts, browser, resolution, headless
• Script runs — status, duration, console errors, network failures, error message, screenshot path, logs
• Deletes — pushed as explicit delete ops that supersede any pending upsert for the same entity

The sync queue

Every change the agent makes (create project, record script, edit a file, complete a run, delete an env var) lands in a local sync_queue table with three fields: entity_type, entity_id, op (upsert or delete). A unique constraint deduplicates repeated edits — only the latest state is pushed.

A background worker drains the queue in a strict order: projects → features → suites → scripts → environments → env vars → suite items → runs. Upserts go before deletes. On failure, each row records last_error, increments attempts, and is retried with exponential backoff.

Offline mode

You can work offline indefinitely. The queue grows; nothing is lost. On the next successful network call the worker drains through every pending op. No feature of the agent requires the server to be reachable.

Pull from cloud

Onboarding a new machine? Click Pull (↓) in the top bar — or run qaclan pull. The agent fetches:

• All projects, features, suites, suite items you (or your team) have pushed
• Script metadata and file content — each script is written to ~/.qaclan/scripts/<local_id>.py
• Environments and env vars
• Recent run history (paginated)

Entities are matched by cloud_id: existing records are upserted, new ones are created.

Reports & Analytics. Team plan

Every cloud surface on qaclan.com — dashboard, reports, AI script analysis — is gated to the Team plan. The free Community plan is local-only: CLI and agent web UI, no cloud views.

Summary tiles

The top strip of the Reports page rolls up the whole workspace into four numbers: average suite health, flaky script count, average pass rate, and average time to green. Quick glance, first thing in the morning.

Suite health

A composite score per suite, graded A–F. The score combines pass rate, flakiness penalty, and trend direction into a single number so you can compare across suites. Rendered as gauges plus a ranked list.

Pass rate trend

Line chart of pass percentage per suite over a 7-, 14-, or 30-day window, plus a direction label: improving, declining, or stable. Click through a suite to see every run that contributed.

Flaky scripts

A script is flagged flaky when it flips between PASSED and FAILED across recent runs. The formula is transitions / (total_runs − 1); anything over 0.3 lands on the flaky list. Rendered as a horizontal bar chart ranked by flakiness %.

Duration trends

Per-script runtime across the last N runs, shown as a table: script name, average duration, trend badge, sparkline, percentage change. Trend classification:

• Critical — runtime ballooning, risk of timeout
• Slowing — measurable slowdown
• Improving — getting faster
• Stable — no meaningful change

Time to green

For every failure incident, the number of runs it took until the suite was green again. Plotted as a bar chart, one bar per incident. Low bars = fast recovery. Long tails = the team left it broken.

Failure-point analysis

When a suite fails, which script fails first? This report ranks scripts by how often they're the earliest failure in a failed suite run — the most common "domino" at the top of a regression.

AI script analysis Team plan

On any script's detail page, Analyze with AI sends the script to Gemini (gemini-2.0-flash) which returns a structured report:

• Quality score — overall 0–100
• Brittleness issues — selectors likely to break, missing waits
• Missing coverage — assertions or edge cases the script skips
• Code quality — structure, readability, duplication
• Summary — one-paragraph TL;DR

The result is cached on the server — open the page later and you see the same report without re-running the model.

Team collaboration. Pro

Invite teammates, share a common view of the workspace and run history, pay per seat. Any teammate can pull the shared workspace and run the same suites locally.

Invite members

From qaclan.com: Team → Invite. Enter an email; we generate an invite token (SHA-256 hashed, 48-hour expiry) and email the link. They accept by signing in with Google using that email.

What's shared

• Projects, features, suites, suite items pushed by any team member
• Scripts — metadata and .py file contents
• Environments and env vars — including values
• Suite runs and script runs — full history with per-script breakdown
• Analytics views — flakiness, trends, suite health

What isn't shared

• Auth keys — one per user, never exposed through the team workspace.
• Local run artifacts — screenshots, full network/console traces, storage state files stay on the machine where the run happened.

Onboarding a new teammate

Once a teammate accepts their invite and logs in to qaclan.com, they get their own auth key from Settings → Auth Key. From there, setup is three commands:

# install the agent (Linux / macOS)
$ curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

# authenticate
$ qaclan login --key <their_auth_key>

# pull the entire team workspace locally
$ qaclan pull
✓ 6 projects · 84 features · 482 scripts · 12 environments

qaclan pull mirrors everything the team has synced — projects, features, suites, suite items, scripts (with their .py file contents recreated under ~/.qaclan/scripts/), and environments with their values. The new teammate can start qaclan serve immediately and run the same regression the rest of the team runs.

Billing & seats

Each active member is a seat at $30/month. Billing runs through Paddle. Add or remove seats any time — proration handled on the next invoice.

CLI reference.

The CLI is for CI, automation, and headless workflows. Everything you can do in the web UI, you can do from the terminal. Run qaclan <command> --help for the exhaustive flag list.

Auth gate

Five commands bypass authentication — login, logout, uninstall, serve, and the hidden _pw-install. Every other command requires a valid stored auth key; unauthenticated calls exit non-zero with a hint to run qaclan login.

Top-level

Project

Environment

Web — Feature

Web — Record

Records a new script via Playwright codegen. Launches a visible browser; when you close it, the captured Python is written to ~/.qaclan/scripts/, runtime-patched, and scanned for {{KEY}} placeholders.

Web — Script

Web — Suite

Web — Run

Execute a suite. --suite accepts a local id, cloud id, or exact suite name within the active project.

# staging smoke on tablet viewport, headless, stop on first failure
$ qaclan web run --suite Smoke --env staging \
    --browser firefox --resolution 1024x768 --headless --stop-on-fail

# all three engines in a loop
for b in chromium firefox webkit; do
  qaclan web run --suite "Full Regression" --browser $b --headless
done

Runs

qaclan runs is a hybrid — invoked without a subcommand it prints the list; the detail view lives under the sibling run group.

API (coming soon)

The api group is scaffolded but not implemented. Subcommands currently print a "coming soon" notice:

• qaclan api feature create|list|delete
• qaclan api suite create|list
• qaclan api run --suite <id> [--env <name>]

Pricing.

Free forever for solo QA — no limit on what you can test locally. Team dashboards and analytics on the Pro plan.

Feature comparison

Changelog.

Recent additions, newest first. Patch releases are folded into their nearest minor entry.