FAQ and troubleshooting

About the product

What is QAClan?

A regression testing tool in two halves. The agent runs on your machine and does the work: recording browser tests, capturing API traffic, organising suites and executing them. The server at qaclan.com is optional and adds shared run history and reports for a team.

Do I need the server?

No. The agent is fully usable alone — recording, imports, suites, runs and local reports all work without it. You log in once so the agent knows who you are. Add the server when more than one person needs the same run history.

Does it work offline?

Yes. Execution is local and sync is best-effort: if the network is down, the command still completes and the queue catches up later.

Where is my data?

In ~/.qaclan/: a SQLite database, your scripts as files, failure screenshots, run artifacts, the isolated runtime, and your auth key in config.json. If you log in, the workspace also syncs to the server.

Do I need to write code?

Not for recording, hardening or assertions. Recorded scripts are plain Playwright in one of four languages if you do want to edit them, and pre/post request scripts accept JavaScript or Python when a check needs real logic.

Can it run in CI?

It can run unattended: qaclan login --key for non-interactive login and qaclan web run --headless for execution without a display. There is no packaged CI plugin and no built-in scheduler — something in your pipeline has to invoke the agent. Recording still needs a display, so author on a desktop.

Which platforms are supported?

Linux amd64, macOS arm64, and Windows on both amd64 and arm64.

Is it open source?

The agent is source available under the Business Source License 1.1. You can read it; it is not an OSI open-source licence.

Is there a trial of the Team plan?

No. Community is free permanently, with no script limit and no time limit, so the part that does the work can be evaluated for as long as you like. See pricing.

Troubleshooting

Recording does not open a browser

Codegen needs a display. Inside Docker, over a plain SSH session, or on a headless server there is nothing to open a window on. Record on your desktop and run the result headless elsewhere.

If you are on a desktop and it still fails, the runtime may be incomplete. Rebuild it:

qaclan reset-runtime --yes && qaclan setup --runtime-only

Runs fail with a missing browser or driver

The agent resolves its own runtime first: the Node binaries under ~/.qaclan/runtime/, then its Python virtual environment, then a system Playwright on PATH. If none are usable, provision it:

qaclan setup --runtime-only

If Chromium was skipped at install time — for example with --no-chromium — re-run setup without that flag.

A globally installed Playwright is interfering

It should not: the runtime is resolved before any global install. If you suspect a clash, rebuild the runtime with qaclan reset-runtime followed by qaclan setup --runtime-only, which restores the pinned versions.

Windows says the publisher is unknown

Choose More info → Run anyway, or unblock the file first:

Unblock-File .\qaclan.exe

A script stops partway through

Each script gets 300 seconds. A journey longer than that should be split into several scripts in one suite — which also makes the failure point obvious. See Suites, runs and reports.

Results are not appearing on the server

Confirm you are logged in, then force a resync rather than waiting for the background queue:

qaclan push --all

Sync failures are deliberately silent so they cannot block a run, which does mean a stale workspace looks like nothing happening.

I am setting up a new machine

qaclan login --key <auth_key> && qaclan pull

That restores projects, features, scripts, collections, environments and suites from the workspace.

Why did my test fail?

Start with the run record — it holds a classified error and what to do about it, plus a screenshot from the moment of failure, console and page errors, and any requests that failed during the run.

qaclan run show <run_id> --verbose