Getting started

Install and set up

1. Install

Add KwikQA as a development dependency of the project that runs your Playwright, Cypress, or WebdriverIO tests. For a JUnit, TestNG, pytest, or other framework's report, you only need Node.js: run it with npx kwikqa.

$ npm i -D kwikqa

Check it with npx kwikqa --version. These docs use npm's commands. With another package manager, install and run KwikQA with its own:

Monorepos

Install KwikQA in the package that holds your tests, and run it from that package's folder, where its kwikqa.config.json goes. KwikQA finds that package's Playwright, Cypress, or WebdriverIO in its own node_modules or in the node_modules of a folder above it, up to the repository root. So the root's node_modules works, but a copy installed only in another package doesn't. It never runs one from outside the repository, so pnpm's global virtual store (enableGlobalVirtualStore) isn't supported.

2. Point KwikQA at your runs

KwikQA reads the report your test runner writes. Pick your framework.

Playwright

Add Playwright's JSON reporter next to your usual one, 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" },
});

Cypress

Use KwikQA's reporter, which ships in the package. It keeps every retry attempt, where each test is declared, and each error's code frame:

// cypress.config.ts
export default defineConfig({
  reporter: "node_modules/kwikqa/dist/cypress-reporter.cjs",
  e2e: { /* ... */ },
});

Already writing mochawesome or JUnit reports? KwikQA reads those too: npx kwikqa analyze --report mochawesome-report. They record only each test's final attempt, so flakiness shows only with KwikQA's reporter.

WebdriverIO

Add KwikQA's reporter next to your own. It keeps the full describe path of every test, which WebdriverIO's JSON and JUnit reporters flatten:

// wdio.conf.ts
import KwikqaReporter from "kwikqa/wdio-reporter";

export const config = {
  reporters: ["spec", [KwikqaReporter, {}]],
  // ...
};

@wdio/json-reporter and @wdio/junit-reporter output works too: point --report at their output directory. WebdriverIO with Mocha or Jasmine is supported; Cucumber is not yet.

Other test frameworks

KwikQA also reads the reports these write, and diagnoses the run:

• Vitest (--reporter=junit), Jest (jest-junit), and Mocha (mocha-junit-reporter);
• pytest (--junitxml);
• Playwright's own junit reporter;
• JUnit and TestNG through Maven Surefire or Failsafe (target/surefire-reports), including Selenium tests;
• JUnit and TestNG through Gradle (build/test-results/test), including the test-retry plugin's retries;
• TestNG's own testng-results.xml;
• Allure results (allure-results) from TestNG, JUnit, Playwright, and pytest;
• CTRF reports, from Playwright, Jest, pytest, and other tools that write them;
• Cucumber's JSON report, from cucumber-js (--format json:<file>) and Cucumber-JVM (the json plugin).

Point --report at the file or its directory:

$ npx kwikqa analyze --report target/surefire-reports --html

You get failure groups, a diagnosis, and the failure report. KwikQA doesn't capture, repair, or validate these runs, and fix says so before it sends anything. For Playwright repairs, use its JSON reporter as shown above.

Some details depend on the reporter:

• TestNG. testng-results.xml keeps retried attempts and failed configuration methods, which Surefire's XML of the same run doesn't correlate. Under Maven, add TestNG's XML reporter to Surefire's configuration (the listener property set to org.testng.reporters.XMLReporter), then point --report at test-output.
• Allure. Allure adds each run's results to its directory, and KwikQA reads the directory as one run, so clean it between runs: mvn clean, or pytest's --clean-alluredir. Otherwise an earlier run's results read as retries.
• Cucumber. Its JSON keeps only each scenario's final attempt, so a scenario that passed on a retry reads as passed. Cucumber-JVM 8 needs a JSON library on the test class path to write it, such as tools.jackson.core:jackson-databind.
• Gradle. Gradle names a JUnit parameterized test by its display name, which includes its arguments. To keep test data out of KwikQA's titles, set junit.jupiter.params.displayname.default = {displayName}[{index}] in junit-platform.properties.
• Jest and pytest. jest-junit records no test file unless you set addFileAttribute: true, and pytest records each test's line only with -o junit_family=xunit1.
• Other producers. JUnit XML from a tool KwikQA doesn't recognize is still read and diagnosed, as an unidentified framework.

Where KwikQA looks

--report takes a report file or a directory of one run's reports. Without it, KwikQA tries the PLAYWRIGHT_JSON_OUTPUT_NAME and KWIKQA_REPORT_DIR environment variables, then test-results/kwikqa-report.json, test-results/kwikqa/ (KwikQA's Cypress and WebdriverIO reporters), playwright-report/results.json, test-results/results.json, mochawesome-report/, cypress/reports/, cypress/results/, results.json, and report.json. A JUnit report that doesn't say which framework wrote it needs --framework cypress or --framework webdriverio.

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.