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?

No. Recording, hardening, assertions, environments, suites and runs are all done in the app at localhost:7823 by clicking. A recorded test is a real Playwright file if you ever want to open it, and pre/post request scripts accept JavaScript or Python when a check needs logic an assertion cannot express — but neither is required to use the product.

Do I need to use the terminal?

Twice, at the very start: once to install the agent, and once to start it with qaclan serve. After that everything happens in the app.

Every action does also have a command, which is what you would use to run tests in CI or to script something repetitive. Those appear throughout the documentation as Prefer the terminal? sections, underneath the way you would do the same thing in the app. See Getting started for the guided route, or the CLI reference for the full command list.

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. Browser run history is not copied down — it stays on the machine that produced it, and remains visible in the cloud workspace.

A test passes sometimes and fails other times

Almost always a timing problem: the test is faster than the page. Three things to try, in order.

1. Reopen the recording's wait review in the editor and accept the waits it suggests.
2. Raise the wait limit for the run, or give that one script an override — see Suites, runs and reports.
3. Check the Flaky Scripts report if you sync, which identifies the scripts doing this across many runs rather than one.

My pre- or post-request script has no effect

A script that errors, times out or exits non-zero has allof its effects discarded — headers, parameters, stored values and assertions — and the request carries on as though it were not there. Nothing is shown as a failure, so “my header is not being set” usually means the script threw before that line.

Wrap the body in qc.test to turn the exception into a visible failed assertion. The most common cause when porting between languages is response status: response.status exists in JavaScript, but Python uses a separate status_code variable. See the Script API reference.

A variable from an extractor rule is empty

Extractor paths are plain dot-paths — data.user.id, with integers indexing arrays — and are not JSONPath. $.data[0].id does not resolve; write data.0.id. A path that does not resolve is skipped silently, and a response that is not JSON skips every rule.

Drift says nothing changed, but I know it did

Where either side of the comparison is an unknown shape — an empty array, or nesting past four levels — no difference is reported, deliberately, because a guess would produce false alarms. Send the request again with a populated array and re-freeze the schema. See Negative testing and schema drift.

Where do screenshots and run artifacts go?

Run artifacts sit inside runtime/, so qaclan reset-runtime clears them along with the dependencies. Everything else survives it. Full layout on Install and setup.

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