Tracing

Capture an append-only recording of a browser session for bug investigation. Every event is written synchronously to a line-delimited JSON file as it happens, so a thrown expect, a failed locator, or a process crash cannot lose the evidence that led up to it.

BiDi-only. Tracing piggybacks on the same BiDi subscriptions used by browser.logs and browser.network. Calling startTrace() without enableBiDi: true throws.

Quick start

import { chromium } from 'craftdriver';

const browser = await chromium.launch({ enableBiDi: true });

await browser.startTrace({ outDir: './artefacts/login' });
try {
  await browser.navigateTo('http://127.0.0.1:8080/login.html');
  await browser.fill('#user', 'alice');
  await browser.click('#submit');
} finally {
  await browser.stopTrace();
}

After the run you get:

artefacts/login/
├── trace.ndjson                  ← one JSON event per line
└── screenshots/
    ├── 0001.png
    └── 0002.png

try/finally is the recommended shape, but it's a courtesy — see the next section.

What happens when a test throws

Every recorded event hits disk before the next line of your test runs (synchronous writeSync on an open file descriptor). So if your test throws halfway through — expect.toBeVisible() times out, a click misses, an a11y check fails — the partial trace.ndjson already contains every action, console message, network event, navigation, and screenshot reference that led up to the failure.

NDJSON has no closing bracket and no header. Partial files are valid NDJSON: any reader simply ignores a truncated final line. The only thing missing when stopTrace() doesn't run is a trailing {"type":"meta","endedAt":"…"} line — readers infer the end time from the last event's t field.

The same is true for screenshots: each PNG is a self-contained file written as the capture resolves, so the ones taken before the failure are intact on disk.

You don't need try/finally for correctness — only to write the closing meta marker and close the file handle cleanly. browser.quit() will close the handle for you on its way out.

What gets recorded

Each line in trace.ndjson is one event. All events carry t (ms since startTrace) and a type:

type	Fields
meta	startedAt / endedAt, opts on the start line
action	name, args?, selector?
console	level, text
error	text (uncaught page errors)
request	url, method, requestId?
response	url, status, mimeType?, fromCache?, requestId?
navigation	url, context?
screenshot	file (relative path), reason ('action' | 'error'), actionIndex?

Actions currently logged: navigateTo, goBack, goForward, reload, setContent, click, fill, clear, acceptDialog, dismissDialog.

Screenshots: evidence, not video

Screenshots are tied to meaningful moments, not a timer:

• Before every logged action — answers "what did the page look like when I clicked?"
• On every page error — answers "what was on screen when it broke?"

A 30-second test with 5 clicks produces 5 PNGs, not 300. Turn it off when you only want the JSON log:

await browser.startTrace({ outDir: './t', screenshots: 'off' });

screenshots: 'auto' (default), true, and omitting the option all mean the same thing.

Selectively disable pillars

Every pillar is on by default. Switch off what you don't need:

await browser.startTrace({
  outDir: './t',
  actions: true,
  screenshots: 'auto',
  network: false,   // skip request/response events
  console: false,   // skip console + error events
});

actions: false keeps the timeline but stops adding action events (and the screenshots that ride along with them).

Reading a trace

NDJSON is trivial to grep, even mid-run:

# All errors and the action that preceded them
jq -c 'select(.type=="error" or .type=="action")' trace.ndjson

# Failed network responses
jq -c 'select(.type=="response" and .status>=400)' trace.ndjson

# Find the screenshot for action #7
jq -c 'select(.actionIndex==7)' trace.ndjson

// Programmatic:
import { readFileSync } from 'node:fs';
const events = readFileSync('trace.ndjson', 'utf8')
  .split('\n').filter(Boolean).map((l) => JSON.parse(l));

Using with Vitest

Vitest doesn't have Playwright-style fixtures, but a small helper using its beforeEach / afterEach hooks gets you automatic per-test tracing with keep-on-failure. One line per describe(), no per-test boilerplate.

Drop this into your test folder (e.g. tests/auto-trace.ts):

import { beforeEach, afterEach } from 'vitest';
import { rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { Browser, TraceScreenshotMode } from 'craftdriver';

const ROOT  = process.env.CRAFTDRIVER_TRACE_DIR ?? './traces';
const MODE  = (process.env.CRAFTDRIVER_TRACE ?? 'on-failure') as
  'always' | 'on-failure' | 'off';
const SHOTS = (process.env.CRAFTDRIVER_TRACE_SCREENSHOTS ?? 'auto') as
  TraceScreenshotMode;

export function autoTrace(getBrowser: () => Browser): void {
  if (MODE === 'off') return;
  let currentDir = '';

  beforeEach(async ({ task }) => {
    currentDir = join(ROOT, safeName(task));
    await getBrowser().startTrace({ outDir: currentDir, screenshots: SHOTS });
  });

  afterEach(async ({ task }) => {
    const failed = task.result?.state === 'fail';
    // Snap the page as it looked at the failed assertion (not just
    // before the last click).
    if (failed) {
      try {
        const buf = await getBrowser().screenshot();
        writeFileSync(join(currentDir, 'final.png'), buf);
      } catch { /* browser may already be dead */ }
    }
    try { await getBrowser().stopTrace(); } catch { return; }
    if (MODE === 'on-failure' && !failed) {
      rmSync(currentDir, { recursive: true, force: true });
    } else if (failed) {
      console.error(`  📁 trace: ${currentDir}`);
    }
  });
}

function safeName(t: { name: string; suite?: { name: string } | null }): string {
  const parts: string[] = [];
  let s: typeof t | null | undefined = t;
  while (s && s.name) { parts.unshift(s.name); s = s.suite; }
  return parts.join('/').replace(/[^a-z0-9/]+/gi, '-').toLowerCase();
}

Use it inside any describe():

import { autoTrace } from './auto-trace';

describe('Login', () => {
  let browser: Browser;
  beforeAll(async () => { browser = await Browser.launch({ enableBiDi: true }); });
  afterAll(async () => { await browser.quit(); });

  autoTrace(() => browser);   // ← that's it

  it('signs in', async () => {
    await browser.navigateTo('http://127.0.0.1:8080/login.html');
    await browser.fill('#user', 'alice');
    await browser.click('#submit');
    // If this expect throws, ./traces/login/signs-in/trace.ndjson is on disk.
  });
});

Knobs are all environment variables — switch behaviour without touching code:

Env var	Values	Default	Effect
CRAFTDRIVER_TRACE	off | on-failure | always	on-failure	What to keep. on-failure deletes traces for passing tests.
CRAFTDRIVER_TRACE_DIR	path	./traces	Root output directory.
CRAFTDRIVER_TRACE_SCREENSHOTS	auto | off	auto	Per the screenshots option. off skips the BiDi capture per action — much faster when you only need the JSON timeline.

Typical workflows:

npm test                                  # green run leaves no clutter; failures keep their trace
CRAFTDRIVER_TRACE_SCREENSHOTS=off npm test    # cheap mode for big suites
CRAFTDRIVER_TRACE=always npm test         # debugging the tracer itself
CRAFTDRIVER_TRACE=off npm test            # tracing disabled

Why a helper and not built-in? Vitest owns the test lifecycle, not craftdriver — and the runner-specific glue (pass/fail detection, hook order, output paths) belongs on your side. The helper is ~30 lines you can read, copy, and adjust to your team's conventions.

API

browser.startTrace(opts)

interface TraceStartOptions {
  outDir: string;                               // required
  actions?: boolean;                            // default true
  network?: boolean;                            // default true
  console?: boolean;                            // default true
  screenshots?: boolean | 'auto' | 'off';       // default 'auto'
}

Creates outDir if missing, opens outDir/trace.ndjson for writing, and emits the start meta line. Throws if a trace is already running or BiDi is not enabled.

browser.stopTrace()

Drains in-flight screenshot captures, writes the closing meta line, and closes the file. Returns Promise<void>. Throws if no trace is running.

Cleanup on browser.quit()

If a trace is still running when you quit the browser, the file is closed without a closing meta line — same shape as the test-throws case. No file is deleted.

What this is not

By design, the tracer does not:

• produce a self-contained .zip or hosted viewer,
• record video / fixed-interval screencast,
• emit HAR (the NDJSON already holds request/response events),
• capture DOM snapshots or sourcemaps.

Those features make sense at much larger scale (Playwright Trace Viewer). For a single failing test, a tail-able NDJSON log plus a handful of PNGs beats a zip you can't open.