@heal-dev/heal-playwright-tracer 1.0.0

package/README.md

@@ -0,0 +1,245 @@
+<h1 align="center">
+  <a href="https://heal.dev/">
+    <img width="240" src="assets/heal-logo.svg" alt="heal">
+  </a>
+</h1>
+<p align="center">
+  <p align="center">Statement-level execution tracing for Playwright tests, purpose-built for AI autopilots.</p>
+</p>
+
+<h4 align="center">
+  <a href="https://app.heal.dev/">SaaS</a> |
+  <a href="https://heal.dev/">Website</a> |
+  <a href="https://docs.heal.dev/">Docs</a>
+</h4>
+
+<h4 align="center">
+  <a href="https://github.com/heal-dev/heal-playwright-tracer/actions/workflows/ci.yml"><img src="https://github.com/heal-dev/heal-playwright-tracer/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://codecov.io/gh/heal-dev/heal-playwright-tracer"><img src="https://codecov.io/gh/heal-dev/heal-playwright-tracer/branch/main/graph/badge.svg" alt="codecov"></a>
+  <a href="https://www.npmjs.com/package/@heal-dev/heal-playwright-tracer"><img src="https://img.shields.io/npm/v/@heal-dev/heal-playwright-tracer.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@heal-dev/heal-playwright-tracer"><img src="https://img.shields.io/node/v/@heal-dev/heal-playwright-tracer.svg" alt="node"></a>
+  <a href="https://www.npmjs.com/package/@playwright/test"><img src="https://img.shields.io/npm/dependency-version/@heal-dev/heal-playwright-tracer/peer/@playwright/test" alt="playwright"></a>
+</h4>
+
+# @heal-dev/heal-playwright-tracer
+
+An AI-agent-first diagnostic layer for Playwright tests. Purpose-built
+to give an autopilot agent everything it needs to reason about _why_
+a test failed — statement-level execution traces with timing,
+variable values, call depth, serialized errors, highlighted locator
+screenshots, and Playwright API correlations — emitted as a
+structured NDJSON stream per test, alongside Playwright's own HTML
+report and trace viewer. Useful to humans too, but every design
+decision optimizes for what an LLM needs to see.
+
+## Install
+
+```sh
+npm install -D @heal-dev/heal-playwright-tracer
+```
+
+Wire the Babel plugin in `playwright.config.ts`.
+
+```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`:
+
+```ts
+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`.
+
+### Extend: custom exporters and lifecycles
+
+`configureTracer` registers extra exporters (fanned out alongside
+the default NDJSON exporter) and per-test setup/teardown pairs —
+useful for shipping traces to your own backend or installing
+per-test globals:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import { configureTracer } from '@heal-dev/heal-playwright-tracer';
+
+configureTracer({
+  exporters: [(ctx) => new MyHttpExporter(ctx.transport)],
+  lifecycles: [
+    () => ({
+      setup: (ctx) => openTelemetrySession(ctx.testInfo),
+      teardown: () => closeTelemetrySession(),
+    }),
+  ],
+});
+
+export default defineConfig({
+  /* ... */
+});
+```
+
+Full surface: [`src/application/heal-config/types.ts`](src/application/heal-config/types.ts).
+Exporters implement [`HealTraceExporter`](src/domain/trace-event-recorder/port/heal-trace-exporter.ts)
+(`write(record)` + `close()`).
+
+## Sample output
+
+`heal-data/heal-traces.ndjson` — one record per line:
+
+```ndjson
+{"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`](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:
+
+```ndjson
+{"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.
+
+## How it works
+
+```
+  Build time (per worker)                        Runtime (per test)
+  ───────────────────────                        ──────────────────
+
+  test file                                      instrumented test
+      │                                                 │
+      ▼                                                 ▼
+  ┌───────────────────┐                         ┌────────────────┐
+  │  Babel plugin     │  ─── instrumented ───►  │  recorder      │
+  │  code-hook-       │      (__enter /         │  enter/ok/     │
+  │  injector         │       __ok / __throw)   │  throw stream  │
+  └───────────────────┘                         └────────┬───────┘
+                                                         │
+                                                         ▼
+                                                 ┌────────────────┐
+                                                 │  statement     │
+                                                 │  projector     │
+                                                 └────────┬───────┘
+                                                          │
+                                                          ▼
+   playwright.config.ts                           ┌──────────────────┐
+   configureTracer({      ─── extends ──────────► │    composite     │
+     exporters,                                   │     exporter     │
+     lifecycles,                                  └───┬──────────┬───┘
+   })                                                 │          │
+                                                      ▼          ▼
+                                                   NDJSON     custom
+                                                    file     exporters
+                                                           (HTTP, queue, …)
+```
+
+The Babel plugin wraps every leaf statement with a try/catch/finally
+that calls three runtime hooks. The recorder pairs those calls into an
+event stream, the projector folds them into `HealTraceRecord`s, and
+a composite exporter fans them out to the default NDJSON file and
+any exporters registered via `configureTracer`.
+
+The plugin also rewrites `from '@playwright/test'` to
+`from '@heal-dev/heal-playwright-tracer'` in every instrumented file,
+so `test` and `expect` automatically resolve to the traced variants —
+no manual import swap required.
+
+## Why CommonJS?
+
+The package ships as CommonJS (no `"type": "module"` in
+`package.json`, `tsc` emits `module: commonjs`). This is deliberate:
+Playwright's babel transform — the thing that actually loads
+`code-hook-injector` — is itself a CJS module and consumes the plugin
+via `require()`. Shipping ESM would force a dual build with no upside.
+
+ESM consumers still work — use `createRequire` in
+`playwright.config.ts` if you need to resolve the plugin path:
+
+```ts
+// playwright.config.ts  (package.json has "type": "module")
+import { defineConfig } from '@playwright/test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export default defineConfig({
+  // @ts-ignore
+  '@playwright/test': {
+    babelPlugins: [[require.resolve('@heal-dev/heal-playwright-tracer/code-hook-injector')]],
+  },
+});
+```
+
+> **The module format of `playwright.config.ts` must match the
+> `"type"` field of its nearest `package.json`.** A mismatch causes
+> Node to route the file through the wrong loader, typically surfacing
+> as `ReferenceError: exports is not defined in ES module scope` —
+> with a stack trace that blames this plugin even though it has never
+> run. If that happens, fix the config format first.
+
+## 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](LICENSE) file for the full text.

package/dist/application/babel-playwright-tracer-plugin/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type * as BabelTypes from '@babel/types';
+import type { PluginObj, PluginPass } from '@babel/core';
+import { type Include } from '../../domain/code-hook-injector/service/traced-file-matcher';
+interface CodeHookInjectorOptions {
+    include?: Include;
+    rootDir?: string;
+}
+declare function codeHookInjector(api: {
+    types: typeof BabelTypes;
+}, opts?: CodeHookInjectorOptions): PluginObj<PluginPass>;
+export = codeHookInjector;

package/dist/application/babel-playwright-tracer-plugin/index.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+const traced_file_matcher_1 = require("../../domain/code-hook-injector/service/traced-file-matcher");
+const cjs_artifact_detector_1 = require("../../domain/code-hook-injector/service/statement-analysis/cjs-artifact-detector");
+const leaf_statement_classifier_1 = require("../../domain/code-hook-injector/service/statement-analysis/leaf-statement-classifier");
+const non_wrappable_statement_1 = require("../../domain/code-hook-injector/service/statement-analysis/non-wrappable-statement");
+const for_head_declaration_detector_1 = require("../../domain/code-hook-injector/service/statement-analysis/for-head-declaration-detector");
+const enclosing_scope_labeler_1 = require("../../domain/code-hook-injector/service/meta-fields/enclosing-scope-labeler");
+const source_snippet_extractor_1 = require("../../domain/code-hook-injector/service/meta-fields/source-snippet-extractor");
+const leading_comment_extractor_1 = require("../../domain/code-hook-injector/service/meta-fields/leading-comment-extractor");
+const relative_file_path_1 = require("../../domain/code-hook-injector/service/meta-fields/relative-file-path");
+const playwright_import_rewriter_1 = require("../../domain/code-hook-injector/service/playwright-import-rewriter");
+const global_trace_call_1 = require("../../domain/code-hook-injector/service/trace-hook/global-trace-call");
+const enter_meta_literal_1 = require("../../domain/code-hook-injector/service/trace-hook/enter-meta-literal");
+const try_finally_wrapper_1 = require("../../domain/code-hook-injector/service/trace-hook/try-finally-wrapper");
+const variable_declaration_hoister_1 = require("../../domain/code-hook-injector/service/trace-hook/variable-declaration-hoister");
+const global_names_1 = require("../../domain/trace-event-recorder/model/global-names");
+function codeHookInjector(api, opts = {}) {
+    const t = api.types;
+    const CWD = opts.rootDir || process.cwd();
+    const matches = (0, traced_file_matcher_1.buildMatcher)(opts.include);
+    const { isGeneratedModuleStatement } = (0, cjs_artifact_detector_1.createCjsArtifactDetector)(t);
+    const { isLeafStatement, kindOf, containsAwait } = (0, leaf_statement_classifier_1.createLeafStatementClassifier)(t);
+    const findScopeName = (0, enclosing_scope_labeler_1.createEnclosingScopeLabeler)(t);
+    const isNonWrappableStatement = (0, non_wrappable_statement_1.createNonWrappableStatementPredicate)(t, isGeneratedModuleStatement);
+    const isForHeadDeclaration = (0, for_head_declaration_detector_1.createForHeadDeclarationDetector)(t);
+    const rewritePlaywrightImports = (0, playwright_import_rewriter_1.createPlaywrightImportRewriter)(t);
+    const callStmt = (0, global_trace_call_1.createGlobalTraceCallBuilder)(t);
+    const buildMeta = (0, enter_meta_literal_1.createEnterMetaLiteralBuilder)(t, {
+        kindOf,
+        containsAwait,
+        findScopeName,
+        extractSource: source_snippet_extractor_1.extractSource,
+        extractLeadingComment: leading_comment_extractor_1.extractLeadingComment,
+        relFile: relative_file_path_1.relFile,
+    });
+    const { buildTryFinally, buildThrewDecl } = (0, try_finally_wrapper_1.createTryFinallyWrapperBuilder)(t, callStmt);
+    const hoistVariableDeclaration = (0, variable_declaration_hoister_1.createVariableDeclarationHoister)(t);
+    return {
+        name: 'heal-playwright-tracer',
+        visitor: {
+            // Rewrite `@playwright/test` → `@heal-dev/heal-playwright-tracer` at
+            // the top of every matched file. Runs before the Statement visitor
+            // because Program.enter fires first. The user keeps the standard
+            // Playwright import; our auto-fixture loads transparently.
+            Program(programPath, state) {
+                if (!matches(state.file.opts.filename || ''))
+                    return;
+                rewritePlaywrightImports(programPath.node);
+            },
+            Statement(stmtPath, state) {
+                const node = stmtPath.node;
+                // Don't recurse into our own generated wrapper.
+                if (node._traced)
+                    return;
+                // Babel sometimes hands us synthetic nodes without source locations.
+                if (!node.loc)
+                    return;
+                // File-level filter: only touch files the consumer opted in to.
+                if (!matches(state.file.opts.filename || ''))
+                    return;
+                // Skip statement kinds that no hook family should wrap.
+                if (isNonWrappableStatement(stmtPath))
+                    return;
+                // Only leaf statements get wrapped. Compound statements
+                // (if/for/while/switch/try) are transparent — their inner
+                // leaves will be visited independently.
+                if (!isLeafStatement(node))
+                    return;
+                // From here on it's trace-hook-specific. When a second hook
+                // family lands, extract the block below into a
+                // `applyTraceHookIfLeaf(stmtPath, state)` function in
+                // ./trace-hook/ and call it alongside the future families.
+                const meta = buildMeta(state, stmtPath, node, CWD);
+                if (t.isVariableDeclaration(node)) {
+                    // `const x = EXPR` can't be wrapped as-is — the binding
+                    // would be scoped to the try block and invisible downstream.
+                    // Hoist the bindings out, assign inside the try, pass a
+                    // vars object to __ok so the recorder can snapshot values.
+                    if (isForHeadDeclaration(node, stmtPath.parent))
+                        return;
+                    const { hoistDecl, assignments, varsObject, bindingNames } = hoistVariableDeclaration(node);
+                    const okArgs = bindingNames.size ? [varsObject] : [];
+                    const { threwId, tryStmt } = buildTryFinally(stmtPath.scope, assignments, okArgs);
+                    stmtPath.replaceWithMultiple([
+                        callStmt(global_names_1.HEAL_ENTER, [meta]),
+                        hoistDecl,
+                        buildThrewDecl(threwId),
+                        tryStmt,
+                    ]);
+                    return;
+                }
+                // Every other leaf statement: wrap in a block with the
+                // original statement inside the try body.
+                node._traced = true;
+                const { threwId, tryStmt } = buildTryFinally(stmtPath.scope, [node]);
+                const wrapper = t.blockStatement([
+                    callStmt(global_names_1.HEAL_ENTER, [meta]),
+                    buildThrewDecl(threwId),
+                    tryStmt,
+                ]);
+                stmtPath.replaceWith(wrapper);
+            },
+        },
+    };
+}
+module.exports = codeHookInjector;

package/dist/application/heal-config/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export { configureTracer, getTracerConfig, onTestTeardown } from './registry';
+export { resetTeardownHooks, drainTeardownHooks } from './registry';
+export type { HealTracerConfig, HealTracerTestContext, HealTraceExporterFactory, HealTestLifecycle, HealTestLifecycleFactory, } from './types';

package/dist/application/heal-config/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.drainTeardownHooks = exports.resetTeardownHooks = exports.onTestTeardown = exports.getTracerConfig = exports.configureTracer = void 0;
+// Public surface of the tracer's extension API.
+//
+// Re-exports what a user needs to extend the tracer from their own
+// `playwright.config.ts`.
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "configureTracer", { enumerable: true, get: function () { return registry_1.configureTracer; } });
+Object.defineProperty(exports, "getTracerConfig", { enumerable: true, get: function () { return registry_1.getTracerConfig; } });
+Object.defineProperty(exports, "onTestTeardown", { enumerable: true, get: function () { return registry_1.onTestTeardown; } });
+// Internal-facing exports — consumed by the fixture only. Kept in the
+// barrel because the fixture imports from this same file; external
+// callers have no reason to touch them.
+var registry_2 = require("./registry");
+Object.defineProperty(exports, "resetTeardownHooks", { enumerable: true, get: function () { return registry_2.resetTeardownHooks; } });
+Object.defineProperty(exports, "drainTeardownHooks", { enumerable: true, get: function () { return registry_2.drainTeardownHooks; } });

package/dist/application/heal-config/registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { HealTracerConfig } from './types';
+/**
+ * Register the tracer's extension config. Typically called once at
+ * the top of `playwright.config.ts`, before `defineConfig(...)`. Later
+ * calls overwrite earlier ones — there is no merge.
+ */
+export declare function configureTracer(config: HealTracerConfig): void;
+/**
+ * Read the currently-registered config. Returns an empty object when
+ * the user never called `configureTracer` — the fixture treats that
+ * as "NDJSON-only, no bindings."
+ */
+export declare function getTracerConfig(): HealTracerConfig;
+/**
+ * Register a function to run when the current test tears down. Runs
+ * BEFORE user bindings' `stop()` so SDKs that use
+ * `onTestTeardown(...)` still see any globals the bindings installed.
+ *
+ * Errors raised by a hook are logged to stderr and swallowed.
+ */
+export declare function onTestTeardown(fn: () => void | Promise<void>): void;
+/**
+ * Internal. Clears the teardown-hook registry. The fixture calls this
+ * at the start of every test to defend against a hook leaking across
+ * test boundaries if a prior test crashed before drain ran.
+ */
+export declare function resetTeardownHooks(): void;
+/**
+ * Internal. Runs every registered teardown hook in registration order,
+ * then clears the registry. Errors are logged and swallowed.
+ */
+export declare function drainTeardownHooks(): Promise<void>;

package/dist/application/heal-config/registry.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureTracer = configureTracer;
+exports.getTracerConfig = getTracerConfig;
+exports.onTestTeardown = onTestTeardown;
+exports.resetTeardownHooks = resetTeardownHooks;
+exports.drainTeardownHooks = drainTeardownHooks;
+let currentConfig = {};
+let teardownHooks = [];
+/**
+ * Register the tracer's extension config. Typically called once at
+ * the top of `playwright.config.ts`, before `defineConfig(...)`. Later
+ * calls overwrite earlier ones — there is no merge.
+ */
+function configureTracer(config) {
+    currentConfig = config;
+}
+/**
+ * Read the currently-registered config. Returns an empty object when
+ * the user never called `configureTracer` — the fixture treats that
+ * as "NDJSON-only, no bindings."
+ */
+function getTracerConfig() {
+    return currentConfig;
+}
+/**
+ * Register a function to run when the current test tears down. Runs
+ * BEFORE user bindings' `stop()` so SDKs that use
+ * `onTestTeardown(...)` still see any globals the bindings installed.
+ *
+ * Errors raised by a hook are logged to stderr and swallowed.
+ */
+function onTestTeardown(fn) {
+    teardownHooks.push(fn);
+}
+/**
+ * Internal. Clears the teardown-hook registry. The fixture calls this
+ * at the start of every test to defend against a hook leaking across
+ * test boundaries if a prior test crashed before drain ran.
+ */
+function resetTeardownHooks() {
+    teardownHooks = [];
+}
+/**
+ * Internal. Runs every registered teardown hook in registration order,
+ * then clears the registry. Errors are logged and swallowed.
+ */
+async function drainTeardownHooks() {
+    const hooks = teardownHooks;
+    teardownHooks = [];
+    for (const hook of hooks) {
+        try {
+            await hook();
+        }
+        catch (err) {
+            console.error('[heal-playwright-tracer] teardown hook failed:', err);
+        }
+    }
+}

package/dist/application/heal-config/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TestInfo } from '@playwright/test';
+import type { HealTraceExporter } from '../../domain/trace-event-recorder/port/heal-trace-exporter';
+/**
+ * Everything the fixture hands to a exporter or lifecycle factory
+ * when a test starts. The `transport` subobject carries the per-test
+ * correlation identifiers any outbound exporter needs.
+ */
+export interface HealTracerTestContext {
+    testInfo: TestInfo;
+    /**
+     * Absolute path to the per-test `heal-data` directory. Created by
+     * the fixture before any factory runs.
+     */
+    healDataDir: string;
+    transport: {
+        /**
+         * Playwright's `testInfo.testId` — stable hash of
+         * (file, title, project). Shared across attempts of the same
+         * test, unique per distinct test. Together with `attempt` it
+         * forms the per-test-attempt correlation key.
+         */
+        testId: string;
+        attempt: number;
+        /** Absolute `testInfo.outputDir`. */
+        rootDir: string;
+    };
+}
+/**
+ * Called once per test. Returns the exporter for that test; the fixture
+ * closes it at teardown via `HealTraceExporter.close()`.
+ */
+export type HealTraceExporterFactory = (ctx: HealTracerTestContext) => HealTraceExporter;
+/**
+ * Per-test setup/teardown pair. Use this to install per-test globals,
+ * open telemetry sessions, patch prototypes you'll unpatch later, etc.
+ *
+ * `setup` receives the `HealTracerTestContext` for the current test.
+ * `teardown` takes no arguments — close over any state you need via
+ * the enclosing factory or class fields.
+ *
+ * Errors in `setup` mark that lifecycle as uninstalled — its
+ * `teardown` will NOT run. Errors in `teardown` are logged and
+ * swallowed so they cannot mask a real test failure.
+ */
+export interface HealTestLifecycle {
+    setup(ctx: HealTracerTestContext): void | Promise<void>;
+    teardown(): void | Promise<void>;
+}
+/**
+ * Factory for a `HealTestLifecycle`. Called once per test, before
+ * `setup`. Always a factory — not a singleton object — so closure
+ * state declared inside the factory is isolated between tests.
+ *
+ * The factory takes no arguments; the `HealTracerTestContext` arrives
+ * via `setup(ctx)` instead. One-place-for-ctx keeps the signature
+ * minimal and avoids the "which ctx do I use?" confusion that a
+ * two-injection design would create.
+ */
+export type HealTestLifecycleFactory = () => HealTestLifecycle;
+/**
+ * Shape of the object passed to `configureTracer(...)`. Both fields
+ * are optional — an empty config yields the default behaviour
+ * (NDJSON-only output, no lifecycles).
+ */
+export interface HealTracerConfig {
+    exporters?: HealTraceExporterFactory[];
+    lifecycles?: HealTestLifecycleFactory[];
+}

package/dist/application/heal-config/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/playwright-fixture/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import { expect as rawExpect } from '@playwright/test';
+import { reset } from '../trace-event-recorder-runtime';
+declare const expect: typeof rawExpect;
+type TraceFixtures = {
+    _traceAuto: void;
+};
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TraceFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect };
+export { reset };