@qa-insight/playwright-reporter

Official QA Insight reporter for Playwright.

Automatically sends the lifecycle of your tests (run start/end and per-test events) to the QA Insight Collector, without modifying your tests: just add a reporter to your configuration.

Installation

npm install --save-dev @qa-insight/playwright-reporter

The package requires @playwright/test >= 1.32 as a peer dependency (already installed if you use Playwright).

Environment variables

| Variable | Default | Description | |---|---|---| | QAI_ENDPOINT | http://localhost:3000/collector/v1/events | QA Insight Collector URL | | QAI_API_KEY | — | QA Insight API key (project + environment) | | QAI_ENABLED | true | false disables the reporter and sends nothing | | QAI_TIMEOUT_MS | 2000 | Per-request HTTP timeout | | QAI_RETRY_MAX | 3 | Retries for transient errors (5xx, 429, network) | | QAI_FLUSH_TIMEOUT_MS | 5000 | Max time the final flush waits | | QAI_RUN_NAME | playwright-run-<timestamp> | Run name | | QAI_RUN_ID | Generated UUID | externalRunId (run idempotency) | | QAI_FRAMEWORK | playwright | Framework label attached to each event | | QAI_PROJECT | — | Informational project label (Playwright project name wins when set) | | QAI_BROWSER | — | Browser label | | QAI_OUTBOX_PATH | <os.tmpdir()>/qa-insight | Directory for the durable outbox file (crash recovery) |

Example:

export QAI_ENDPOINT=http://localhost:3000/collector/v1/events
export QAI_API_KEY=qai_...
export QAI_ENABLED=true
export QAI_TIMEOUT_MS=2000
export QAI_RETRY_MAX=3

Configuration in playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    [
      '@qa-insight/playwright-reporter',
      {
        endpoint: process.env.QAI_ENDPOINT,
        apiKey: process.env.QAI_API_KEY,
        enabled: true,
      },
    ],
    ['list'],
  ],
});

Explicit options take precedence over environment variables.

Available options (all optional):

| Option | Description | |---|---| | endpoint | Overrides QAI_ENDPOINT | | apiKey | Overrides QAI_API_KEY | | enabled | Overrides QAI_ENABLED | | timeoutMs | Overrides QAI_TIMEOUT_MS | | retryMax | Overrides QAI_RETRY_MAX | | flushTimeoutMs | Overrides QAI_FLUSH_TIMEOUT_MS | | runName | Overrides QAI_RUN_NAME | | externalRunId | Overrides QAI_RUN_ID | | project | Overrides QAI_PROJECT | | framework | Overrides QAI_FRAMEWORK | | outboxPath | Overrides QAI_OUTBOX_PATH; set to '' to disable disk persistence | | redactPatterns | Additional RegExp[] to redact secrets | | redactValues | Literal string[] values to redact | | ci | Overrides CI/CD detection (branch, commitSha, pipelineUrl, runId, buildId) |

Events sent

| Playwright moment | QA Insight event | |---|---| | onBegin | RUN_STARTED | | onTestBegin | TEST_STARTED | | onTestEnd | TEST_FINISHED | | onEnd (run completed) | RUN_FINISHED | | onEnd (timeout / interruption) | RUN_ABORTED |

Each event includes eventId (UUID), occurredAt, externalRunId, run name, suite, test, status, duration, retry index, framework: "playwright", project/browser, and redacted errors/stacktraces.

Crash recovery

The reporter is resilient to process death, so a run never stays stuck in RUNNING:

• Every event is appended and fsynced to a durable outbox file (<os.tmpdir()>/qa-insight/<runId>.jsonl by default) before it is sent.
• If onEnd is never reached (the run is killed or interrupted), an onExit() hook emits RUN_ABORTED so the run finalizes.
• On the next run, the reporter recovers events a previous process died before delivering (SIGKILL, OOM, crash) and, when that stale run never emitted a terminal event, sends a synthetic RUN_ABORTED on its behalf. Re-sends are deduplicated by the Collector via Idempotency-Key. Files owned by still-running processes are never adopted.
• Outbox files are removed once the run finalizes.

CI/CD integration

The reporter automatically detects (with no configuration) the variables of:

• GitHub Actions (GITHUB_ACTIONS, GITHUB_REF_NAME, GITHUB_SHA, GITHUB_REPOSITORY, GITHUB_RUN_ID)
• GitLab CI (GITLAB_CI, CI_COMMIT_BRANCH, CI_COMMIT_SHA, CI_PIPELINE_URL, CI_PIPELINE_ID)
• Jenkins (JENKINS_URL, BRANCH_NAME, GIT_COMMIT, BUILD_URL, BUILD_NUMBER)
• Azure DevOps (TF_BUILD, BUILD_SOURCEBRANCH, BUILD_SOURCEVERSION, BUILD_BUILDURI, BUILD_BUILDID)

Only non-sensitive metadata is captured: branch, commit SHA, pipeline/build URL, run ID and provider. You can override it from playwright.config.ts:

reporter: [
  [
    '@qa-insight/playwright-reporter',
    {
      ci: {
        branch: 'release/1.0',
        commitSha: process.env.MY_COMMIT,
        pipelineUrl: process.env.MY_PIPELINE_URL,
      },
    },
  ],
],

GitHub Actions integration

name: e2e
on: [push]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          QAI_ENDPOINT: http://localhost:3000/collector/v1/events
          QAI_API_KEY: ${{ secrets.QAI_API_KEY }}

Behavior on network failures

• The reporter never changes the result of a Playwright test.
• If QA Insight is unreachable, a local warning is logged and the tests continue.
• Transient errors (timeout, network, 5xx, 429) are retried with exponential backoff (QAI_RETRY_MAX).
• Permanent errors (4xx) are not retried.
• Events are buffered and a bounded flush (QAI_FLUSH_TIMEOUT_MS) runs at the end.
• The API key is never printed in logs or included in payloads.

Data policy and redaction

Before sending errorMessage and stacktrace, the reporter redacts by default:

• Authorization headers and Bearer/token values
• password, passwd, secret, api-key, cookie
• QA Insight API keys (qai_...), Slack tokens (xox*)

You can add your own patterns and values:

reporter: [
  [
    '@qa-insight/playwright-reporter',
    {
      redactPatterns: [/customerid\s*[:=]\s*\S+/gi],
      redactValues: [process.env.INTERNAL_SECRET!],
    },
  ],
],

Evidence

Screenshots, videos and traces are not uploaded yet. If Playwright generates attachments, only the reference/metadata (name, contentType) is sent in test.evidence, and the backend stores them as metadata. Access to evidence is controlled by the evidence:read permission (the Developer role does not include it by default; it only sees sanitized errorMessage/stacktrace via test_results:read_details). Secure upload to object storage will arrive in a future version.

Complete example

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  reporter: [
    [
      '@qa-insight/playwright-reporter',
      {
        endpoint: process.env.QAI_ENDPOINT,
        apiKey: process.env.QAI_API_KEY,
        enabled: true,
        timeoutMs: 2000,
        retryMax: 3,
        runName: `e2e-${process.env.GITHUB_RUN_ID ?? 'local'}`,
      },
    ],
    ['list'],
  ],
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
});

See also the runnable example in examples/playwright-basic.

Version compatibility

• Node.js >= 18 (uses native fetch).
• @playwright/test >= 1.32 (uses the public Reporter interface).
• Event contract: schemaVersion: "1.0" against the QA Insight Collector.
• The package is published with a dual ESM + CommonJS build (conditional exports).

Development

npm install
npm run build      # ESM + CJS + dts build into dist/
npm test           # unit + contract + integration (vitest)
npm run typecheck

License

MIT