@tracelane/core

The framework-agnostic recording engine behind tracelane. Wraps any test runner's browser object behind one BrowserExecutor interface and drives the rrweb capture. Shared internals — not installed directly.

Framework-agnostic recording engine for tracelane. Wraps a per-framework browser object behind a common BrowserExecutor interface, injects the rrweb capture bundle, drains in-page events to Node, and builds the buffer that the report packages render.

Not intended for direct consumption — depend on a product package instead:

npm install --save-dev @tracelane/wdio        # WebdriverIO Service
npm install --save-dev @tracelane/playwright  # Playwright reporter + fixture
# @tracelane/cypress — on the roadmap

See the @tracelane/wdio README for the integration guide.

What's in here

• BrowserExecutor — the framework-agnostic surface that adapters implement.
• Recorder controller — in-page buffer install + Node-polled drain.
• Navigation re-injection with a 250ms cooldown + tracelane.nav boundary events.
• Mode switch ('failed' | 'all') and a 25 MB FullSnapshot-preserving report-size guard.

Built on @cubenest/rrweb-core.

Exact internal values (cooldown ms, report-size cap) are the calibrated defaults at the time of writing; see src/recorder.ts and src/size-guard.ts for the source of truth.

API

The public surface is re-exported from src/index.ts. The load-bearing contract is the BrowserExecutor interface that every adapter implements — @tracelane/core only ever talks to it, never to a concrete framework driver:

export interface BrowserExecutor {
  execute<T>(fn: (...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
  executeAsync<T>(fn: (...args: unknown[]) => void, ...args: unknown[]): Promise<T>;
  cdp(domain: string, command: string, params?: Record<string, unknown>): Promise<unknown>;
  on(event: string, handler: (params: unknown) => void): void;
}

Also exported: createRecorder (the recorder controller), attachNetworkCapture (CDP network capture), loadRrwebBundle, the resolveMode mode switch, and the pruneToSizeBudget report-size guard. See src/browser-executor.ts for the full interface docs.

Related packages

• @cubenest/rrweb-core — the shared rrweb fork + network plugin this engine builds on.
• @tracelane/wdio — WebdriverIO adapter (implements BrowserExecutor).
• @tracelane/playwright — Playwright adapter (implements BrowserExecutor).
• @tracelane/report — builds the self-contained HTML report from the captured buffer.
• @tracelane/cli — wires the adapters together for a project.

License

Apache-2.0. Contributions require a DCO sign-off (git commit -s).

See the CHANGELOG for release history and SECURITY-NOTES for the recording/redaction threat model.