Suites, runs and reports
A suite is an ordered list of steps that runs as one unit and produces one record. The order matters, because the steps share state.
Building a suite
qaclan web suite create "checkout regression"qaclan web suite add --suite <suite_id> --script <script_id>add appends to the end. To set an exact order, pass the full list:
qaclan web suite reorder --suite <suite_id> --scripts <id1>,<id2>,<id3>| Command | What it does |
|---|---|
qaclan web suite list | Every suite with its script count and last-run status |
qaclan web suite show --suite <id> | The scripts in order, plus first and last run status |
qaclan web suite remove --suite <id> --script <id> | Take a script out of the suite, leaving the script itself alone |
qaclan web suite delete <suite_id> | Delete the suite. The underlying scripts are not deleted |
Shared state across steps
Every script in a suite runs inside one shared browser context. Cookies and localStorage set by the first script are still there in the fourth, so you log in once and the rest of the suite is already authenticated. That is why order is meaningful rather than decorative.
Values also travel between steps: a post-request script can write to shared state with qc.set(key, value), and later steps read it as a variable — see API testing.
Running a suite
qaclan web run --suite <id_or_name> --env staging| Flag | Effect |
|---|---|
--env <name> | Load that environment's variables for the duration of the run |
--browser chromium|firefox|webkit | Which engine to run in |
--resolution WxH | Viewport size, for example 1440x900 |
--headless | Run with no visible browser window |
--stop-on-fail | Skip the remaining scripts after the first failure, rather than failing them |
--stop-on-fail marks the rest as skipped, not failed, which keeps a broken login from producing twenty misleading failures.
Each script gets 300 seconds
A single script that runs longer than five minutes is stopped. Long journeys are better split into several scripts in one suite — which also makes it obvious where a failure happened.
What a run records
For every script in the run:
- Status and duration
- Console errors and warnings, and page errors
- Network requests that failed during the run
- On failure: a screenshot, saved under
~/.qaclan/screenshots/ - On failure: a classified error with a plain-language explanation and what to do about it
Reading results
qaclan runsqaclan runs --suite <suite_id>One row per run: suite, status, scripts passed out of total, start time and duration. For the detail of a single run:
qaclan run show <run_id>This prints per-script results, and for failures the classified error — category, message, what to do, and diagnostics such as the failing selector, the timeout or the URL where available. Add --verbose for the raw traceback.
qaclan run show <run_id> --verboseOffline HTML reports
A report is a single self-contained file. No server is needed to open it, so it can be attached to a ticket or emailed to whoever needs to see the failure.
qaclan runs report <run_id>qaclan runs report <run_id> --output release-42.htmlWithout --output it writes qaclan-report-<run_id>.html to the current directory.
Running unattended
Non-interactive login plus headless execution covers a machine with nobody sitting at it:
qaclan login --key <auth_key>qaclan web run --suite checkout --headless --stop-on-failWhere browsers are already staged on the machine, skip the download during setup with qaclan setup --no-chromium.
Recording still needs a display
Only execution works headless. qaclan web record and qaclan api record open a real browser window, so author on a desktop and run elsewhere. There is no packaged CI plugin and no built-in scheduler — the agent runs when something invokes it.
Checking a project at a glance
qaclan statusPrints every web and API feature in the active project with its script count, warns about features that have no scripts yet, and ends with a one-line summary.