Trace8 documentation

Playwright test reporting and trace debugging

Run Playwright locally or in CI, sync structured results to one dashboard, and open private screenshots and traces without replacing your existing test suite.

Quick start

Create a Trace8 project, open its settings, and create a project token. Then install the CLI in the same repository as @playwright/test.

npm install --save-dev @trace8/cli
npx --no-install trace8 init
npx --no-install trace8 test

The token is saved with private file permissions in .trace8/config.json, and .trace8/ is added to .gitignore. Trace8 masks common secret patterns before log output is sent.

Playwright configuration

Trace8 uses the Playwright installation already pinned by your project. Configure Playwright to retain only the debugging artifacts your team needs.

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

export default defineConfig({
  use: {
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
    video: "off",
  },
});

Playwright retries are collapsed into one result while repeatEach occurrences stay distinct, so flakiness history remains accurate without losing repeated executions.

CLI commands

trace8 init

Validate a project token and create private local configuration.

trace8 test

Run the local Playwright binary, sync results, upload artifacts, and finalize the run.

trace8 upload <report.json>

Sync an existing Playwright JSON reporter file and its available attachments.

trace8 doctor

Check configuration, API access, Playwright resolution, and artifact output.

trace8 unlink

Remove current and legacy local Trace8 configuration.

--require-upload

Fail an otherwise passing CI job when artifact synchronization is incomplete.

npx --no-install trace8 test --env staging --require-upload -- \
  --project=chromium --grep="checkout"

CI setup

Store the project token in your CI provider's encrypted secret store as TRACE8_TOKEN. Do not commit a token or the .trace8 directory.

- run: npm ci
- run: npx playwright install --with-deps chromium
- name: Run and sync Playwright
  run: npx --no-install trace8 test --env production --require-upload -- --project=chromium
  env:
    TRACE8_TOKEN: ${{ secrets.TRACE8_TOKEN }}

You can also set TRACE8_API_URL and TRACE8_ENV. The default API origin is https://tplay.dev.

Artifacts and traces

The API returns short-lived upload URLs so screenshots, traces, videos, and attachments move directly from the CLI to private Backblaze B2 storage. Opening an artifact requires an authenticated Trace8 session and a new short-lived read URL. Artifacts are retained for 14 days by default; run metadata and flakiness history remain.

Failed tests appear first. From a failed run, choose View Traceto open the signed trace in Playwright Trace Viewer, or open the test detail for its error, stack, screenshot, retry count, exact repeat occurrence, and history.

Troubleshooting

Run npx --no-install trace8 doctor before changing configuration.
If Playwright is missing, install @playwright/test and the browser binaries in your project.
If results sync without artifacts, verify the Playwright capture settings and that attachment files still exist.
If a token was exposed, revoke or rotate it immediately from project settings.
For support or responsible disclosure, email [email protected].