Using KwikQA
Commands
analyze
$ npx kwikqa analyze [--report <path>] [--framework <name>] [--local] [--yes] [--capture] [--no-probe] [--no-changes] [--html [--output <path>]]
Diagnoses the failures in a Playwright, Cypress, or WebdriverIO report, or one from the other frameworks KwikQA reads. The first line of the result says what it read, such as Read a Cypress 16.2.0 run (KwikQA reporter): 8 tests, 5 failing, 1 flaky.
| Option | Effect |
|---|---|
--report <path> | Read this report file, or every report file in this directory, instead of looking in the default locations. |
--framework <name> | playwright, cypress, or webdriverio: the framework of a JUnit report that doesn't name one. Other formats name their own. |
--local | Build the evidence summary on your machine only. Nothing is sent, and no account is needed. |
--yes | Approve the request preview without asking. Needed when there is no terminal, as in CI. |
--capture | First re-run the failing tests with your project's own runner, so every failure has full evidence. Playwright runs them with full tracing. Cypress and WebdriverIO re-run the failing spec files with your config, plus KwikQA's reporter and failure capture, which records each failed attempt's DOM, command log, console, and network. It shows the exact command and asks before running it; --yes approves. Output goes to .kwikqa/capture/, and fix uses it until you run your tests again. Java and Python runs can't be captured yet. |
--no-changes | Leave recent code changes that mention the failures out of the evidence. |
--html | Also write the failure report, kwikqa-report.html. |
--output <path> | With --html, write the report here instead. KwikQA replaces only a file it wrote itself. |
--no-probe | With --capture, skip the live probe. Otherwise, on Playwright 1.59 or later with Playwright CLI installed, KwikQA pauses up to three locator failures at the failing line and asks Playwright for locators of the closest elements. |
report
$ npx kwikqa report [--run <id>] [--output <path>]
Writes the failure report of the latest analysis without analyzing again or sending anything. It rebuilds the evidence from the same test report and artifacts, and says so if they have changed since.
| Option | Effect |
|---|---|
--run <id> | An earlier run, by its id under .kwikqa/runs/. |
--output <path> | Where to write it; the default is kwikqa-report.html. |
fix
$ npx kwikqa fix [--report <path>] [--propose-only] [--retry] [--no-changes] [--group <n>]
Proposes a repair for a test-support cause, shows the diff and validation commands, and applies the patch if you approve. For a Java, Python, or Cucumber-JVM failure, its failing tests must be end-to-end browser tests; a unit test is diagnosed but not repaired. It needs kwikqa.config.json and an interactive terminal, because a person approves every patch. The one exception is CI: in GitHub Actions, Azure Pipelines, or GitLab CI/CD, a committed ci.fix policy lets it validate the repair on the runner and open it as a draft pull request, which a person merges: see Fix pull requests.
| Option | Effect |
|---|---|
--report <path> | Repair from this report. |
--propose-only | Stop after showing the proposal. Nothing is applied. |
--retry | After a failed validation, re-diagnose from the validation evidence and propose one revised patch. Free. In CI, the policy's retry decides instead. |
--no-changes | Leave out recent code changes, as analyze --no-changes does. |
--group <n> | Repair only failure group n, as analyze numbered it. |
validate
$ npx kwikqa validate
Runs the validation plan you approved with the patch, with your project's own Playwright, Cypress, WebdriverIO, Maven, Gradle, or pytest. If every required check passes, the patch is kept. Otherwise it is rolled back. It sends nothing and counts nothing.
check
$ npx kwikqa check [--base <ref>] [--analysis <path>] [--yes]
Checks test changes KwikQA didn't write, such as a coding agent's or Playwright's healer's, with the gates KwikQA's own repairs pass: scope and policy, ownership by an analysis of the code before the change, and validation. For a change to a test file, validation re-runs each touched failing test three times in a row with retries off. For a change to shared test support, it runs every test that uses the change: once for Maven, Gradle, and pytest runs, Cucumber-JVM included, and three times for Playwright, Cypress, and WebdriverIO. A change to a Java, Python, or Cucumber-JVM test that KwikQA can't confirm reaches a browser library isn't checked, and the verdict is incomplete unless another gate fails. It exits 0 when every gate passed. It sends nothing to KwikQA and counts nothing. In CI it publishes its verdict on the pull request. See Checking outside changes.
ci
$ npx kwikqa ci [--report <path>] [--framework <name>] [--local] [--no-changes] [--output <path>] [--notify on-failure|always]
For a CI job after failing tests. It analyzes the run as analyze --yes does, writes the failure report, kwikqa-report.html, and publishes a summary of the run: on GitHub Actions, the job summary and one pull-request comment; on Azure Pipelines, a build summary and one pull-request thread; on GitLab CI/CD, the job's log and one merge-request note; on Jenkins, the console log and one comment on a GitHub or GitLab pull request. On any CI system, it can also post a Slack or Teams message through your webhooks. Without a usable KwikQA token, it analyzes locally and says why. It exits with the analysis's own exit code: anything it can't publish is reported and skipped. See Running in CI.
| Option | Effect |
|---|---|
--report, --framework, --local | As for analyze. |
--no-changes | Leave recent code changes out of the evidence. |
--output <path> | Write the failure report here instead of kwikqa-report.html. KwikQA replaces only a file it wrote itself. |
--notify <when> | When to post to Slack and Teams: on-failure (the default: when tests failed) or always. |
Account commands
| Command | What it does |
|---|---|
npx kwikqa init | Propose and write kwikqa.config.json, offer to ignore .kwikqa/, and show the reporter setup for each framework the project uses. |
npx kwikqa login | Sign in: approve the code it shows at kwikqa.com/device, while signed in to the website. From 0.5.0 it opens that page in your browser with the code filled in; --no-browser only prints the page and the code, and it never opens a browser in CI or without a terminal. |
npx kwikqa status | Show your plan, this month's usage, and when it resets. In a company account, it also shows your role, the team this sign-in counts for, and whether insights are on (0.5.0). |
npx kwikqa upgrade [plan] | List plans, or get a checkout link for pro, team, byo, byo-team, enterprise, or byo-enterprise. Paid plans are coming soon, so for now it lists them without a checkout link. --annual bills yearly (two months free); --seats <n> sets seats on team plans (3 or more on Teams and BYOK Teams; 12 or more on Enterprise and BYOK Enterprise). Pro and BYOK are for a personal account, and the team plans for a company account's admins. If you already pay, it points you to Billing in the dashboard instead. |
npx kwikqa billing | Open Paddle's customer portal to update your card or download invoices. |
npx kwikqa logout | Revoke this machine's token and remove it. |
npx kwikqa --version | Print the version. |
Environment variables
| Variable | Used for |
|---|---|
KWIKQA_TOKEN | A CLI or CI token, used instead of the stored sign-in. Create one in the dashboard. |
KWIKQA_ENDPOINT | The model endpoint on the BYOK plans: openrouter (the default), anthropic, openai, azure-openai, bedrock, or github-models. Each endpoint's credentials are listed on Bring your own key. |
OPENROUTER_API_KEY | Your OpenRouter key, on the BYOK plans with the default endpoint. |
KWIKQA_DIAGNOSIS_MODEL, KWIKQA_REPAIR_MODEL | Your own models on the BYOK plans: on OpenRouter, routes as author/model@provider; on the other endpoints, the endpoint's own model ID or deployment, and the diagnosis model is required. |
PLAYWRIGHT_JSON_OUTPUT_NAME | Where to find a Playwright report, if set. |
KWIKQA_REPORT_DIR | Where KwikQA's Cypress and WebdriverIO reporters write, and where analyze looks, if set. |
GITHUB_TOKEN | With ci, the token that writes the pull-request comment: on GitHub Actions the job's own, which needs pull-requests: write; on Jenkins one you bind, for a pull request on GitHub. With fix in GitHub Actions, it also opens the fix pull request, and needs contents: write too. |
SYSTEM_ACCESSTOKEN | With ci on Azure Pipelines, the build's System.AccessToken, mapped in the step's env, which writes the pull-request thread. With fix, it also pushes the fix branch and opens its pull request. |
GITLAB_TOKEN | With ci on GitLab CI/CD, or on Jenkins for a merge request on GitLab, the token that writes the merge-request note. With fix on GitLab CI/CD, it also pushes the fix branch and opens its merge request, so it needs the api scope and at least the Developer role. |
KWIKQA_SLACK_WEBHOOK_URL, KWIKQA_TEAMS_WEBHOOK_URL | With ci, the Slack and Teams webhooks to post to. |
KWIKQA_SHARD | With ci on the Enterprise plans, the name of this job, where the CI system's own job id isn't unique per shard, such as ${{ matrix.shard }}. See Sharded suites. |
JAVA_HOME | For Maven and Gradle validation: the JDK, already installed, that runs the build. KwikQA never installs one. |
MAVEN_USER_HOME, GRADLE_USER_HOME | For Maven and Gradle validation: the user home that holds the wrapper's unpacked distribution, if not ~/.m2 or ~/.gradle. KwikQA never downloads one. |
KWIKQA_CONFIG_DIR | Where the CLI keeps its sign-in. Defaults to ~/.config/kwikqa, or %APPDATA%\kwikqa on Windows. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success, or an informative result such as diagnosed or inconclusive. |
1 | The repair or validation did not succeed: repair-failed, validation-unavailable, or operation-failed. |
2 | Usage error: an unknown option, or a command that needs a terminal. |
3 | Sign-in, plan, or usage-limit problem. |