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!

Install

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

Wire the Babel plugin 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\//] },
      ],
    ],
  },
});

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

declare module '@playwright/test' {
  interface Config {
    '@playwright/test'?: {
      babelPlugins?: Array<[string, object?]>;
    };
  }
}

Per-test output lands at
test-results/<test>/heal-data/heal-traces.ndjson.

Optional: capture worker crashes

When a Playwright worker dies before the fixture can finalize its
trace (OOM, SIGKILL, segfault, process.exit()), the per-test
NDJSON is left without its test-result terminator. Register the
reporter to have the Playwright main process append a synthesized
test-result carrying the classified crash cause (e.g.
OutOfMemoryError, WorkerCrash):

// playwright.config.ts
export default defineConfig({
  reporter: [['@heal-dev/heal-playwright-tracer/reporter']],
  // ...
});

Fully optional and idempotent: on the common case where the fixture
finalizes cleanly, the reporter is a no-op.

Usage

1. After installing Heal, run your tests with the usual npx playwright test command.
2. You should see heal-traces.ndjson.
3. You can ask Claude or another agent to use those to understand your test results.

Claude Skill

See this Claude skill for a starter.

Sample output

heal-data/heal-traces.ndjson — one record per line:

{"kind":"test-header","schemaVersion":1,"test":{"title":"it works","file":"tests/example.spec.ts","context":{"testId":"...","attempt":1}}}
{"kind":"statement","statement":{"loc":{"line":5},"source":"await page.goto('https://example.com')","durationMs":412,"status":"ok","children":[...]}}
{"kind":"statement","statement":{"loc":{"line":6},"source":"await expect(page.getByRole('heading')).toBeVisible()","durationMs":73,"status":"ok"}}
{"kind":"test-result","status":"passed","duration":1234,"stdout":"...","stderr":""}

Schema: src/domain/trace-event-recorder/model/statement-trace-schema.ts
(also exported as @heal-dev/heal-playwright-tracer/statement-trace-schema).

Screenshots

Every statement that calls a patched Playwright locator action
(click, fill, hover, press, …) or a locator assertion
(expect(locator).toBeVisible(), toHaveText(), …) produces a
PNG screenshot with the targeted element outlined via an overlay
drawn in-page — so the agent sees what Playwright was actually
pointing at at the moment the action ran, not just the raw page.

Files are written to the per-test heal-data/ directory and
referenced on the corresponding statement via the screenshot
field:

{"kind":"statement","statement":{"source":"await page.getByRole('button', { name: 'Submit' }).click()","status":"ok","screenshot":"stmt-0007.png"}}
{"kind":"statement","statement":{"source":"await expect(page.getByRole('alert')).toBeVisible()","status":"ok","screenshot":"stmt-0008.png"}}

Statements that don't touch a locator (plain JS, utility calls,
page.goto) have no screenshot field — capture is scoped to the
Playwright surface where it adds diagnostic signal.

Architecture, and extending the tracer

See development.md

Caveats

The Babel plugin rewrites every leaf statement with a try/catch/finally
and three hook calls — the same shape of transformation Istanbul applies
for code coverage. Two consequences to be aware of:

• Instrumented files are larger. Each statement gains a wrapper, so
  on-disk size of transformed test files grows noticeably (typically
  ~2–4×, depending on statement density). This affects the files
  Playwright loads into workers, not your application bundle.
• Tests run slightly slower. The per-statement hook overhead is
  small in absolute terms but not free — expect a modest slowdown on
  CPU-bound test code. I/O-bound tests (the common case: await page.click(...), network, navigation) are dominated by the browser
  and barely move.

Scope the include filter in playwright.config.ts so only your
tests/ directory is instrumented — never your app code or
node_modules — to keep the cost contained.

License

Copyright © 2026 MYIA SAS.

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See the LICENSE file for the full text.