Open-source statement-level Playwright tracer, purpose-built for AI agents.

SaaS | Website | Docs

@heal-dev/heal-playwright-tracer

heal-playwright-tracer is an agent-first diagnostic layer for your Playwright tests. It gives agents (and humans) everything they need to quickly analyze test results.

👉 Add this to your playwright config, run your tests, point Claude to the improved heal trace, get more accurate test diagnosis

Why

The playwright trace doesn't contain enough data for LLM-based agents such as Claude or Open Code to analyze tests results reliably. That's because the trace ifs focused on locator evaluation, while real-life tests also evaluate non-playwright code. Heal adds the missing instrumentation layer to let LLM agents work their magic. And it's useful for humans in complex test codebases, too!

Feature	Playwright Trace	Heal Tracer	Example: What Heal Adds
Granularity	Action-level	Statement-level	Shows let x = calculate() line-by-line, not just the final page.click().
Data Format	ZIP/Binary	NDJSON Stream	{"type":"step","file":"auth.spec.ts","line":12,"val":{"user":"dev"}}
Visual Context	Standard screenshots	Highlighted locators	An image where the target button is outlined in a neon overlay to prove hit-box accuracy.
Variable State	Limited/Debugger only	Full Variable Values	Captures that status_code was 403 inside a hidden helper function.
Error Detail	Standard stack trace	Serialized Errors	A JSON object containing the DOM snapshot at the exact millisecond of the throw.
Timing	Action durations	Per-statement timing	Identifies that a specific if statement logic took 2.5s to evaluate.
Correlations	Loose logs/network	API Correlations	Links Trace_ID_99 directly to Source_Line_45 in the NDJSON stream.
Electron	Fixture page only	The app's windows	An app launched with _electron.launch() is recorded on video and captured like the page.

Install

npm install -D @heal-dev/heal-playwright-tracer

Wire the Babel plugin and the reporter in playwright.config.ts:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  // @ts-ignore — `babelPlugins` is a supported Playwright option not yet in its public types
  '@playwright/test': {
    babelPlugins: [
      [
        require.resolve('@heal-dev/heal-playwright-tracer/code-hook-injector'),
        { include: [/\/tests\//] },
      ],
    ],
  },
  reporter: [['@heal-dev/heal-playwright-tracer/reporter']],
});

Both are required: if you wire the Babel plugin without the reporter, the fixture fails fast on the first test of every worker. For why the reporter is mandatory (crash rescue, Playwright attachment copy, execution-history index), see docs/configuration.md.

If you prefer to keep the config fully typed, declare the babelPlugins option once at the top of the file instead of using @ts-ignore: