Using KwikQA

Checking outside changes

Coding agents and Playwright's healer change tests too. kwikqa check holds those changes to the same gates KwikQA's own repairs pass, so a test can't be made green by weakening it. It reads your files and runs your tests on your machine or runner. It sends nothing to KwikQA and counts nothing toward your plan.

$ npx kwikqa check [--base <ref>] [--analysis <path>] [--yes]

The gates

A change passes only when every gate passes. Each finding names its file and line.

1. Scope and policy. Only the test paths your committed kwikqa.config.json makes editable may change, within the same repair rules: no skips, fixme, fixed waits, added retries, forced actions, swallowed errors, or removed, swapped, or loosened assertions.
2. Ownership. The failing tests the change touches must have been diagnosed as the test's fault, by an analysis of the code before the change. Run npx kwikqa analyze on the failing run before the agent edits the test. A change to a test whose failure was the application's fault fails the check, because the test may have caught a real bug.
3. Validation. Each touched failing test must pass three times in a row with retries off, and the static checks must pass. KwikQA shows the exact commands and asks before running anything; --yes approves.

Verdicts and exit codes

Options

Putting a failed change back

After a failed check of uncommitted changes, at a terminal, KwikQA offers to put the changed files back as HEAD has them. It keeps a copy of the change in .kwikqa/adopted/ first, so nothing is lost. Only a yes at the terminal restores anything. It never offers to restore in CI.

As a required check on pull requests

In CI, kwikqa check publishes its verdict where kwikqa ci publishes its summary: the job summary and one pull-request comment of its own (on Azure Pipelines, a build summary and a pull-request thread; on GitLab, the log and a merge-request note; on Jenkins, the log and a pull-request comment). A pass only updates an earlier comment. Because failed and incomplete exit 1, branch protection can require the job.

on:
  pull_request:
    paths: ["tests/**"]
permissions:
  contents: read
  pull-requests: write # only for the comment
jobs:
  kwikqa-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # check compares with the base branch
      - run: npm ci && npx playwright install --with-deps
      - run: npx kwikqa check --base origin/${{ github.base_ref }} --analysis failing-run/result.json --yes
        env:
          GITHUB_TOKEN: ${{ github.token }}