tracelane

Getting started

From install to a replayable failure in ~2 minutes.

Pick your runner: WebdriverIO · Playwright.

WebdriverIO

1. Install

In an existing WebdriverIO project:

pnpm add -D @tracelane/wdio @tracelane/core @tracelane/report

Or with npm / yarn: npm i -D @tracelane/wdio @tracelane/core @tracelane/report.

webdriverio and @wdio/types are peer dependencies (^9.0.0) — you already have them in a WDIO project.

2. Register the service

Add TracelaneService to the services array in wdio.conf.ts:

// wdio.conf.ts
import type { Options } from '@wdio/types';
import TracelaneService from '@tracelane/wdio';

export const config: Options.Testrunner = {
  runner: 'local',
  framework: 'mocha',
  specs: ['./test/specs/**/*.ts'],
  capabilities: [
    {
      browserName: 'chrome',
      'goog:chromeOptions': {
        args: ['--remote-debugging-port=9222', '--no-sandbox'],
      },
    },
  ],
  services: [
    ['devtools', {}], // enables browser.cdp() for network capture
    [
      TracelaneService,
      {
        mode: 'failed',           // 'failed' (default) or 'all'
        outDir: './tracelane',    // report output dir
        capture: { rrweb: true, network: true, console: true },
      },
    ],
  ],
  reporters: ['spec'],
};

3. Run your tests

Run your suite normally:

pnpm wdio run wdio.conf.ts
On failure: a self-contained HTML report is written to tracelane/<spec>--<title>--<cid>-<ts>.html. Open it in any browser to scrub through the rrweb session, inspect console logs, and see failed responses — entirely offline. One file, no server.

4. Options

Full options reference, the traceLaneHooks alternative (for setups that can't register a Service), and the Mocha / Jasmine / Cucumber notes are in the package README:

Advisory security hygiene (on by default): reports include a collapsed Security hygiene panel surfacing missing security headers, insecure cookies, mixed content, and reverse tabnabbing — derived from the session tracelane already captures. The same findings appear in the Copy-as-Markdown-for-AI output. It's advisory, not an audit or a scanner. The mixed-content and reverse-tabnabbing checks read the rrweb DOM snapshot and work on any browser; the header and cookie checks need the CDP network path (Chromium with CDP active) and are skipped when it isn't. Disable the whole layer with security: false in the service options, or suppress individual findings with a tracelane.security.suppress.json file in your project root. 
services: [[TracelaneService, { security: false }]],

Browser & framework support

Verified install path

The maintainer's end-to-end walk of this getting-started flow lives in the repo at docs/qa/tracelane-qa.md — a copy-pasteable checklist plus a runnable WDIO fixture (docs/qa/fixtures/tracelane-demo) you can use to reproduce the same passing/failing scenarios.

Playwright

1. Install

In an existing Playwright project (@playwright/test ≥ 1.40):

npm i -D @tracelane/playwright
Shortcut: npx @tracelane/cli init detects your Playwright project, installs @tracelane/playwright, and registers the reporter in playwright.config.* for you. You still do step 3 (swap the spec import to the fixture) by hand — the CLI prints the exact line to change. The manual steps below are the same thing done yourself.

2. Register the reporter

Add the tracelane reporter to the reporter array in playwright.config.ts:

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

export default defineConfig({
  reporter: [
    ['list'],
    ['@tracelane/playwright', { mode: 'failed', outDir: './tracelane-reports' }],
  ],
});

3. Use the fixture

Swap the import in your spec files:

import { test, expect } from '@tracelane/playwright/fixture';

The fixture is auto — every test in files that import this test is recorded. No per-test wiring required.

4. Run and open the report

npx playwright test
On failure: a self-contained HTML report is written to ./tracelane-reports/<spec>--<title>--<project>-<ts>.html. Open it in any browser, fully offline — rrweb replay, console panel, and failed-network panel, no server required.

Notes: network is captured in-page by the rrweb/network@1 plugin on every browser (Chromium / Firefox / WebKit) — no CDP required; on Chromium tracelane additionally uses CDP to enrich the panel with authoritative status and true no-response failures. Recording continues across page.goto navigations; tracelane coexists with Playwright's own trace option.

Further reading

Questions or issues? Open one on GitHub.