Getting started

Install and set up

1. Install

Add KwikQA as a development dependency of the project that runs your Playwright tests:

$ npm i -D kwikqa

With pnpm use pnpm add -D kwikqa; with Yarn, yarn add -D kwikqa. Check it with npx kwikqa --version.

2. Add the JSON reporter

KwikQA reads Playwright's JSON report. Add it next to your usual reporter, and keep traces for failures so the diagnosis can cite what the browser actually did:

// playwright.config.ts
export default defineConfig({
  reporter: [["list"], ["json", { outputFile: "test-results/kwikqa-report.json" }]],
  use: { trace: "retain-on-failure" },
});

KwikQA looks for the report in this order: the --report option, the PLAYWRIGHT_JSON_OUTPUT_NAME environment variable, then test-results/kwikqa-report.json, playwright-report/results.json, test-results/results.json, results.json, and report.json.

3. Create the repair policy

$ npx kwikqa init

init looks at the files git tracks and proposes a kwikqa.config.json listing which files KwikQA may edit. It writes the file only if you agree, and offers to add .kwikqa/ (local run records) to .gitignore. Review and commit the config like any other code. Configuration explains every field.

4. Sign in

$ npx kwikqa login
Open https://github.com/login/device and enter the code: WDJB-MJHT
Signed in as octocat.

Sign-in uses your GitHub account; the free plan needs no payment details. The CLI stores its token in your user configuration directory, never in the project. Check your plan and usage with:

$ npx kwikqa status

5. Run it

After a run with failures, continue with your first repair. To try KwikQA without an account or sending anything, run npx kwikqa analyze --local: it builds the evidence summary on your machine only.