@heal-dev/heal-playwright-tracer 1.0.0 → 1.0.8

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

@@ -3,8 +3,10 @@
  * 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 { BrowserContext, Request as PwRequest, TestInfo } from '@playwright/test';
 import type { HealTraceExporter } from '../../domain/trace-event-recorder/port/heal-trace-exporter';
+import type { ConsoleLevel } from '../../domain/trace-event-recorder/model/console-trace-schema';
+import type { EnterMeta } from '../../domain/trace-event-recorder/model/enter-meta';
 /**
  * Everything the fixture hands to a exporter or lifecycle factory
  * when a test starts. The `transport` subobject carries the per-test
@@ -13,8 +15,12 @@ import type { HealTraceExporter } from '../../domain/trace-event-recorder/port/h
 export interface HealTracerTestContext {
     testInfo: TestInfo;
     /**
-     * Absolute path to the per-test `heal-data` directory. Created by
-     * the fixture before any factory runs.
+     * Absolute path to the per-(test, attempt) directory under the
+     * persistent history root — `<cwd>/heal-traces/<executionId>/<testId>/<attempt>/`.
+     * Created by the fixture before any factory runs. The ndjson, the
+     * per-statement screenshots, and any reporter-copied Playwright
+     * artefacts (trace.zip, video, failure screenshots) all land
+     * inside this directory.
      */
     healDataDir: string;
     transport: {
@@ -26,8 +32,26 @@ export interface HealTracerTestContext {
          */
         testId: string;
         attempt: number;
-        /** Absolute `testInfo.outputDir`. */
+        /**
+         * Per-process executionId resolved at fixture time
+         * (HEAL_EXECUTION_ID, else uuidv4).
+         */
+        executionId: string;
+        /**
+         * Absolute path to the per-(test, attempt) directory under the
+         * persistent heal-traces tree — same as `healDataDir`. Kept on
+         * `transport` so exporters that ship artefacts out-of-band have
+         * a stable name for the directory they should consult.
+         */
         rootDir: string;
+        /**
+         * Absolute path to the per-test `heal-traces.ndjson` file the
+         * default NDJSON exporter writes to. Sourced from
+         * `HealTracesLayout` so it reflects the real on-disk location.
+         * Exporters that ship artifacts out-of-band can use this as the
+         * authoritative location of the per-test trace file.
+         */
+        healTracesFilePath: string;
     };
 }
 /**
@@ -63,11 +87,168 @@ export interface HealTestLifecycle {
  */
 export type HealTestLifecycleFactory = () => HealTestLifecycle;
 /**
- * Shape of the object passed to `configureTracer(...)`. Both fields
+ * Context passed to a `StatementPreProcessor` on every call. Extends
+ * `HealTracerTestContext` with the live `browserContext` for the
+ * current test so a pre-processor can read pages, evaluate scripts,
+ * stamp DOM, etc. before the user's statement runs.
+ *
+ * `browserContext` is the same object Playwright passes to the test —
+ * pre-processors share it with the test body, so any mutation the
+ * pre-processor makes is visible to the statement that follows.
+ */
+export interface StatementPreProcessorContext extends HealTracerTestContext {
+    browserContext: BrowserContext;
+}
+/**
+ * Async function called once per traced leaf statement, before the
+ * statement body runs. The Babel plugin emits
+ * `await globalThis.__heal_preprocess?.(meta)` inside the try block;
+ * the fixture installs a single global that loops over every
+ * registered pre-processor in declaration order and awaits each.
+ *
+ * Async-context only: the emit is gated on the enclosing function
+ * being `async`. Statements inside synchronous helpers skip the
+ * pre-processor chain entirely (we cannot `await` from a sync
+ * function).
+ *
+ * Errors thrown by a pre-processor are caught by the statement's own
+ * try/catch — they will be reported as a `__heal_throw` for the
+ * statement, NOT swallowed silently. Pre-processors should therefore
+ * be defensive about their own internal failures (try/catch, log,
+ * return) when a partial side-effect is acceptable.
+ *
+ * Plain function — no class, no factory, no setup/teardown. Bind a
+ * method if you need instance state; or close over module-scoped
+ * state in `playwright.config.ts`.
+ */
+export type StatementPreProcessor = (input: {
+    meta: EnterMeta;
+    ctx: StatementPreProcessorContext;
+}) => void | Promise<void>;
+/**
+ * Caps applied to async work the tracer wraps around the user's
+ * test. Both fields are optional; the fixture falls back to sensible
+ * defaults when omitted. The point of these caps is that the tracer
+ * must never outlast the work it is decorating — a hung overlay
+ * cleanup or a wedged user exporter must surface and unblock the
+ * test rather than hang it.
+ */
+export interface HealTracerTimeouts {
+    /**
+     * Cap on every async the screenshot pipeline awaits — locator
+     * resolution (`boundingBox`, `locator.evaluate`), overlay draw /
+     * remove (`page.evaluate`), every CDP send (`Overlay.*`,
+     * `Page.captureScreenshot`, `Runtime.*`), `newCDPSession`, and
+     * the `page.screenshot` fallback. Capture is best-effort: on
+     * timeout the screenshot is dropped and the action proceeds.
+     * Default: 10_000ms.
+     */
+    screenshotMs?: number;
+    /**
+     * Cap on user-extensible per-test work — each lifecycle `setup` /
+     * `teardown`, the drained `onTestTeardown` hook chain, and the
+     * final `projector.finalize` (which closes every registered
+     * exporter). On timeout the fixture logs to stderr and continues
+     * with the next teardown step. Default: 30_000ms.
+     */
+    lifecycleMs?: number;
+}
+/**
+ * When and how the network adapter inlines request/response bodies.
+ *   - `'never'` (default): bodies are never read; only `bytes` is
+ *     populated when known via `Content-Length`. Cheapest option.
+ *   - `'always'`: textual bodies under `maxBodyBytes` are inlined as
+ *     `requestBody.preview` / `responseBody.preview` on every record.
+ *   - `'on-error'`: bodies are buffered in memory while the test
+ *     runs and flushed as separate `network-body` records ONLY if
+ *     the test ends in a failing status. Discarded otherwise. Useful
+ *     for keeping the happy-path light while still getting payloads
+ *     for failing runs.
+ */
+export type HealTracerNetworkBodyMode = 'never' | 'always' | 'on-error';
+/**
+ * Tunables for `heal-network.ndjson` capture. Capture is on by
+ * default; pass `enabled: false` to suppress the stream. Tests and
+ * exceptional setups use this; the public configuration docs treat
+ * network capture as always-on.
+ */
+export interface HealTracerNetworkConfig {
+    /** Pass `false` to suppress the stream. Defaults to `true`. */
+    enabled?: boolean;
+    /** See `HealTracerNetworkBodyMode`. Defaults to `'never'`. */
+    bodyMode?: HealTracerNetworkBodyMode;
+    /**
+     * Per-body cap in bytes. Bodies larger than this are not buffered;
+     * the record records `bytes` and sets `truncated: true`. Default:
+     * 8192.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Headers (case-insensitive) the adapter MUST strip from both
+     * request and response headers before writing. Merged with a
+     * baked-in default denylist (`authorization`, `cookie`,
+     * `set-cookie`, `proxy-authorization`, `x-api-key`, `x-auth-token`)
+     * — provide additional names here to extend, not replace, that
+     * list.
+     */
+    redactHeaders?: string[];
+    /**
+     * Predicate to drop requests entirely before they reach the
+     * coalescer. Return `false` to skip a request (e.g. ignore noisy
+     * telemetry endpoints). Errors thrown by this function are
+     * swallowed and the request is kept.
+     */
+    urlFilter?: (url: string, request: PwRequest) => boolean;
+    /**
+     * Content-type allowlist for body inlining. A response whose
+     * `Content-Type` does not match any of these regexes will record
+     * `bytes` only, no `preview`. Defaults cover textual payloads
+     * (`text/*`, `application/json`, `application/xml`,
+     * `application/x-www-form-urlencoded`, `application/javascript`).
+     */
+    contentTypeAllowlist?: RegExp[];
+}
+/**
+ * Tunables for `heal-console.ndjson` capture. On by default; pass
+ * `enabled: false` to suppress the stream. Same opt-out story as
+ * `HealTracerNetworkConfig`.
+ */
+export interface HealTracerConsoleConfig {
+    /** Pass `false` to suppress the stream. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Levels to keep. Anything else is dropped before being written.
+     * Default keeps everything (`['log','info','warn','error','debug','trace','pageerror']`).
+     */
+    levels?: ConsoleLevel[];
+    /**
+     * Per-arg cap in bytes — the JSON-serialized form of any single
+     * `console.*` argument is truncated past this. Default: 4096.
+     */
+    maxArgBytes?: number;
+    /**
+     * Cap on the number of args kept per console event. Default: 10.
+     */
+    maxArgsPerEvent?: number;
+}
+/**
+ * Shape of the object passed to `configureTracer(...)`. All fields
  * are optional — an empty config yields the default behaviour
- * (NDJSON-only output, no lifecycles).
+ * (statement-stream NDJSON + network and console sidecars, no
+ * lifecycles, default timeouts).
  */
 export interface HealTracerConfig {
     exporters?: HealTraceExporterFactory[];
     lifecycles?: HealTestLifecycleFactory[];
+    /**
+     * Per-statement async hooks. Each function in this array is awaited
+     * before the user's statement runs (gated on the enclosing function
+     * being `async`). Useful for pre-execution side-effects that must
+     * complete before Playwright resolves a locator — e.g. stamping the
+     * DOM with attributes a custom selector strategy depends on.
+     */
+    preProcessors?: StatementPreProcessor[];
+    timeouts?: HealTracerTimeouts;
+    network?: HealTracerNetworkConfig;
+    console?: HealTracerConsoleConfig;
 }

package/dist/application/playwright-fixture/index.js

@@ -64,13 +64,14 @@ exports.reset = exports.expect = exports.test = void 0;
 //                   lifecycle teardowns so SDKs still see any globals
 //                   a lifecycle installed
 //
-// Output shape (per test): `heal-data/heal-traces.ndjson` — one
-// HealTraceRecord per line. See
+// Output shape (per (test, attempt)):
+//   <cwd>/heal-traces/<executionId>/<playwrightTestId>/<attempt>/heal-traces.ndjson
+// The fixture writes the ndjson + per-statement screenshots there;
+// the reporter additionally copies Playwright artefacts (trace.zip,
+// videos, failure screenshots, user attachments) into the same dir
+// on `onTestEnd`. See
 // `../../domain/trace-event-recorder/model/statement-trace-schema.ts`
-// for the contract.
-//
-// Env toggles:
-//   HEAL_TRACE_NDJSON   default on; set to `0`/`false`/`off` to disable.
+// for the record contract.
 //
 // Any backend integration (HTTP shipping, APM bindings,
 // telemetry-session setup, …) lives in user code and plugs in via
@@ -90,79 +91,207 @@ const playwright_step_tracking_adapter_1 = require("../../infrastructure/playwri
 const playwright_test_context_adapter_1 = require("../../infrastructure/playwright-test-context-adapter");
 const playwright_locator_screenshot_adapter_2 = require("../../infrastructure/playwright-locator-screenshot-adapter");
 const stdout_capture_adapter_1 = require("../../infrastructure/stdout-capture-adapter");
+const playwright_console_capture_adapter_1 = require("../../infrastructure/playwright-console-capture-adapter");
+const playwright_network_capture_adapter_1 = require("../../infrastructure/playwright-network-capture-adapter");
+const heal_traces_layout_1 = require("../../infrastructure/heal-traces-layout");
+const artifact_summary_printer_1 = require("../../infrastructure/artifact-summary-printer");
+const heal_reporter_1 = require("../../infrastructure/heal-reporter");
 const heal_config_1 = require("../heal-config");
+const with_timeout_1 = require("../../util/with-timeout");
+const logger_1 = require("../../util/logger");
+const wire_all_pages_1 = require("./wire-all-pages");
+const global_names_1 = require("../../domain/trace-event-recorder/model/global-names");
+// Defaults for the optional `timeouts` block in `HealTracerConfig`.
+// `screenshotMs` caps best-effort decoration calls in the screenshot
+// pipeline; `lifecycleMs` caps user setup/teardown and the final
+// projector close. On `lifecycleMs` timeouts the fixture logs to
+// stderr and continues the rest of teardown — a hung user exporter
+// must not block the next test from starting.
+const DEFAULT_SCREENSHOT_TIMEOUT_MS = 10000;
+const DEFAULT_LIFECYCLE_TIMEOUT_MS = 30000;
 // Wrap `expect` so any assertion made against a Locator gets a
 // highlight screenshot stamped onto the active statement, the same
 // way locator actions do. Non-locator assertions fall through.
 const expect = (0, playwright_locator_screenshot_adapter_1.wrapExpect)(test_1.expect);
 exports.expect = expect;
-// All artifacts this package produces live under this subdirectory of
-// `testInfo.outputDir`, so they stay segregated from Playwright's own
-// output (screenshot/trace/video attachments).
-const HEAL_DATA_SUBDIR = 'heal-data';
-const NDJSON_FILENAME = 'heal-traces.ndjson';
-function envFlag(name, defaultOn) {
-    const raw = process.env[name];
-    if (raw == null || raw === '')
-        return defaultOn;
-    const v = raw.toLowerCase();
-    if (v === '0' || v === 'false' || v === 'off' || v === 'no')
-        return false;
-    return true;
-}
-function buildHealTraceExporter(healDataDir, ctx) {
-    const legs = [];
-    if (envFlag('HEAL_TRACE_NDJSON', true)) {
-        legs.push(new ndjson_exporter_adapter_1.NdjsonExporter(path.join(healDataDir, NDJSON_FILENAME)));
-    }
+function buildHealTraceExporter(ndjsonPath, ctx) {
+    const legs = [new ndjson_exporter_adapter_1.NdjsonExporter(ndjsonPath)];
     const { exporters = [] } = (0, heal_config_1.getTracerConfig)();
     for (const factory of exporters) {
         try {
             legs.push(factory(ctx));
         }
         catch (err) {
-            console.error('[heal-playwright-tracer] exporter factory failed:', err);
+            logger_1.log.error('exporter factory failed', err);
         }
     }
-    if (legs.length === 0) {
-        // Neither leg active — return a no-op exporter so the projector
-        // still runs without doing anything user-visible.
-        return { write() { }, async close() { } };
-    }
     return legs.length === 1 ? legs[0] : new service_1.CompositeHealTraceExporter(legs);
 }
 // Composition-root singletons — one per process.
-const testContextAdapter = new playwright_test_context_adapter_1.PlaywrightTestContextAdapter({ setContext: trace_event_recorder_runtime_1.setContext });
+const testContextAdapter = new playwright_test_context_adapter_1.PlaywrightTestContextAdapter({ setContext: trace_event_recorder_runtime_1.setContext }, { resolveExecutionId: heal_traces_layout_1.resolveExecutionId });
 const stepTrackingAdapter = new playwright_step_tracking_adapter_1.PlaywrightStepTrackingAdapter({ pushStep: trace_event_recorder_runtime_1.pushStep, popStep: trace_event_recorder_runtime_1.popStep });
+// The Babel plugin and the reporter are a pair — the in-worker fixture
+// produces NDJSON; the reporter (main process) propagates the
+// executionId, finalizes crashed traces, and copies Playwright
+// artefacts. Running the plugin without the reporter silently produces
+// half-broken output, so we hard-fail the first test in each worker.
+// Reporter sets HEAL_TRACER_REPORTER=1 in onBegin; Playwright
+// propagates env to workers.
+let reporterCheckPassed = false;
+function assertReporterRegistered() {
+    if (reporterCheckPassed)
+        return;
+    if (process.env.HEAL_TRACER_REPORTER !== '1') {
+        throw new Error('@heal-dev/heal-playwright-tracer: Babel plugin is wired but the ' +
+            'reporter is not registered. Add to playwright.config.ts:\n' +
+            "  reporter: [['@heal-dev/heal-playwright-tracer/reporter']]\n" +
+            'See https://github.com/heal-dev/heal-playwright-tracer#register-the-reporter');
+    }
+    reporterCheckPassed = true;
+}
 exports.test = test_1.test.extend({
     _traceAuto: [
-        async ({ page }, use, testInfo) => {
+        async ({ page, browser, request }, use, testInfo) => {
+            assertReporterRegistered();
             const captured = testContextAdapter.capture(testInfo);
-            const healDataDir = path.join(testInfo.outputDir, HEAL_DATA_SUBDIR);
-            fs.mkdirSync(healDataDir, { recursive: true });
+            const layout = new heal_traces_layout_1.HealTracesLayout(process.cwd(), captured.executionId);
+            const testDir = layout.testDir(captured.testId, captured.attempt);
+            const ndjsonPath = layout.ndjsonPath(captured.testId, captured.attempt);
+            const screenshotsDir = path.dirname(layout.screenshotPath(captured.testId, captured.attempt, 'x.png'));
+            fs.mkdirSync(testDir, { recursive: true });
+            fs.mkdirSync(screenshotsDir, { recursive: true });
+            // Write a registry entry for the optional `HealTracerReporter`
+            // so it can find this test's NDJSON from the main process.
+            // Filesystem-based (not annotation/attachment) because
+            // Playwright's IPC does not flush fixture-pushed annotations
+            // on abrupt worker exit (OOM / SIGKILL / `process.exit()`) —
+            // exactly the crash cases the reporter rescues. A file
+            // written with writeSync before the test body runs survives
+            // any subsequent abrupt exit. Cleaned up in the `finally`
+            // block below on graceful teardown, so only crashed tests
+            // leave an orphan for the reporter to pick up.
+            const registryPath = (0, heal_reporter_1.healPendingRegistryPath)(testInfo.project.outputDir, captured.testId, captured.attempt);
+            fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+            fs.writeFileSync(registryPath, JSON.stringify({
+                ndjsonPath,
+                rootDir: testDir,
+                executionId: captured.executionId,
+                playwrightOutputDir: testInfo.outputDir,
+            }), 'utf8');
             const tracerCtx = {
                 testInfo,
-                healDataDir,
+                healDataDir: testDir,
                 transport: {
                     testId: captured.testId,
                     attempt: captured.attempt,
-                    rootDir: testInfo.outputDir,
+                    executionId: captured.executionId,
+                    rootDir: testDir,
+                    healTracesFilePath: ndjsonPath,
                 },
             };
+            // Network and console sidecar streams are on by default. A
+            // user can still opt out per-stream via
+            // `configureTracer({ network: { enabled: false }, ... })` —
+            // the field stays settable for tests and exceptional setups,
+            // but the public docs treat the streams as always-on.
+            const tracerConfig = (0, heal_config_1.getTracerConfig)();
+            const networkEnabled = tracerConfig.network?.enabled !== false;
+            const consoleEnabled = tracerConfig.console?.enabled !== false;
+            const networkPath = networkEnabled
+                ? layout.networkNdjsonPath(captured.testId, captured.attempt)
+                : undefined;
+            const consolePath = consoleEnabled
+                ? layout.consoleNdjsonPath(captured.testId, captured.attempt)
+                : undefined;
             // Fresh output pipeline per test: build a HealTraceExporter (default
             // NDJSON leg + any user-configured exporters), wrap it in a
             // projector, install on the recorder, then reset() — which
             // clears projector state and emits the test-header record via
             // the buildMetaEvent call inside the recorder.
-            const output = buildHealTraceExporter(healDataDir, tracerCtx);
+            const output = buildHealTraceExporter(ndjsonPath, tracerCtx);
             const projector = new projectors_1.StatementProjector(output);
             (0, trace_event_recorder_runtime_1.setExporter)(projector);
             (0, trace_event_recorder_runtime_1.reset)();
             // Defensive: clear any teardown hooks that leaked from a
             // previous test that crashed before drain ran.
             (0, heal_config_1.resetTeardownHooks)();
-            const stopScreenshots = (0, playwright_locator_screenshot_adapter_2.startLocatorScreenshotCapture)(page, healDataDir, trace_event_recorder_runtime_1.setCurrentStatementScreenshot);
+            const { timeouts = {} } = tracerConfig;
+            const screenshotTimeoutMs = timeouts.screenshotMs ?? DEFAULT_SCREENSHOT_TIMEOUT_MS;
+            const lifecycleTimeoutMs = timeouts.lifecycleMs ?? DEFAULT_LIFECYCLE_TIMEOUT_MS;
+            const stopScreenshots = (0, playwright_locator_screenshot_adapter_2.startLocatorScreenshotCapture)(page, screenshotsDir, trace_event_recorder_runtime_1.setCurrentStatementScreenshot, screenshotTimeoutMs);
             const stdoutSession = new stdout_capture_adapter_1.StdoutCaptureSession();
+            // Sidecar capture: instantiate sessions for whichever streams
+            // the user opted into, wire the test's initial context first
+            // (so the very first request issued by the test body is
+            // captured even if it races a popup) and then patch
+            // `browser.newContext` / `browser.newPage` so any context the
+            // test creates later is also wired. The patches are reverted
+            // by `restoreWiring()` in the finally block — `browser` is
+            // worker-scoped, so a stale patch would leak into the next
+            // test in the same worker.
+            const consoleSession = consoleEnabled && consolePath
+                ? new playwright_console_capture_adapter_1.ConsoleCaptureSession(consolePath, {
+                    clock: trace_event_recorder_runtime_1.clock,
+                    startedAt: (0, trace_event_recorder_runtime_1.getStartedAt)(),
+                    getCurrentStatementSeq: trace_event_recorder_runtime_1.getCurrentStatementSeq,
+                    getCurrentStepPath: trace_event_recorder_runtime_1.getCurrentStepPath,
+                }, tracerConfig.console ?? {})
+                : undefined;
+            const networkSession = networkEnabled && networkPath
+                ? new playwright_network_capture_adapter_1.NetworkCaptureSession(networkPath, {
+                    clock: trace_event_recorder_runtime_1.clock,
+                    startedAt: (0, trace_event_recorder_runtime_1.getStartedAt)(),
+                    getCurrentStatementSeq: trace_event_recorder_runtime_1.getCurrentStatementSeq,
+                    getCurrentStepPath: trace_event_recorder_runtime_1.getCurrentStepPath,
+                }, tracerConfig.network ?? {})
+                : undefined;
+            const wireableSessions = [];
+            if (consoleSession)
+                wireableSessions.push(consoleSession);
+            if (networkSession)
+                wireableSessions.push(networkSession);
+            let restoreWiring;
+            if (wireableSessions.length > 0) {
+                // Wire the test's primary BrowserContext + APIRequestContext
+                // immediately, then patch the Browser for any new contexts.
+                for (const s of wireableSessions)
+                    s.attachToContext(page.context());
+                if (networkSession) {
+                    networkSession.attachToApiRequestContext(request);
+                }
+                restoreWiring = (0, wire_all_pages_1.wireAllPages)(wireableSessions, {
+                    browser,
+                    apiRequest: test_1.request,
+                });
+            }
+            // Install per-statement pre-processor chain on `globalThis`. The
+            // Babel plugin emits `await globalThis.__heal_preprocess?.(meta)`
+            // inside every async-context leaf statement; with no
+            // pre-processors registered the slot stays `undefined` and the
+            // optional call is a no-op. With one or more registered, the
+            // installed function loops over them in declaration order and
+            // awaits each. Errors propagate out of the chain (and into the
+            // statement's own try/catch) — a pre-processor that wants to
+            // be defensive about its own failures has to handle them.
+            //
+            // Installed BEFORE lifecycles so a lifecycle's `setup` can
+            // exercise pre-processed code paths if it triggers traced
+            // statements (rare but cleanly defined). Uninstalled AFTER
+            // lifecycle teardowns for the symmetric reason.
+            const preProcessors = tracerConfig.preProcessors ?? [];
+            const preprocessCtx = {
+                ...tracerCtx,
+                browserContext: page.context(),
+            };
+            const g = globalThis;
+            const previousPreprocess = g[global_names_1.HEAL_PREPROCESS];
+            if (preProcessors.length > 0) {
+                g[global_names_1.HEAL_PREPROCESS] = async (meta) => {
+                    for (const pp of preProcessors) {
+                        await pp({ meta, ctx: preprocessCtx });
+                    }
+                };
+            }
             // Instantiate user-configured lifecycles for this test. Each
             // factory runs fresh per test so any closure state the factory
             // declares is isolated between tests. Setup failures are
@@ -174,11 +303,11 @@ exports.test = test_1.test.extend({
             for (const factory of lifecycles) {
                 try {
                     const lc = factory();
-                    await lc.setup(tracerCtx);
+                    await (0, with_timeout_1.withTimeout)(Promise.resolve(lc.setup(tracerCtx)), lifecycleTimeoutMs, 'lifecycle.setup');
                     activeLifecycles.push(lc);
                 }
                 catch (err) {
-                    console.error('[heal-playwright-tracer] lifecycle setup failed:', err);
+                    logger_1.log.error('lifecycle setup failed', err);
                 }
             }
             try {
@@ -190,20 +319,66 @@ exports.test = test_1.test.extend({
                 // still see the per-test globals a lifecycle installed, and
                 // BEFORE stopping stdout capture so SDK teardown output lands
                 // in the ndjson's `test-result.stdout/stderr`.
-                await (0, heal_config_1.drainTeardownHooks)();
+                try {
+                    await (0, with_timeout_1.withTimeout)((0, heal_config_1.drainTeardownHooks)(), lifecycleTimeoutMs, 'onTestTeardown hooks');
+                }
+                catch (err) {
+                    logger_1.log.error('teardown hooks did not finish', err);
+                }
                 // Teardown in reverse order (LIFO): the last lifecycle to set
                 // up is the first to tear down, matching the mental model of
                 // nested `using` blocks.
                 for (let i = activeLifecycles.length - 1; i >= 0; i--) {
                     try {
-                        await activeLifecycles[i].teardown();
+                        await (0, with_timeout_1.withTimeout)(Promise.resolve(activeLifecycles[i].teardown()), lifecycleTimeoutMs, 'lifecycle.teardown');
                     }
                     catch (err) {
-                        console.error('[heal-playwright-tracer] lifecycle teardown failed:', err);
+                        logger_1.log.error('lifecycle teardown failed', err);
                     }
                 }
+                // Uninstall the per-statement pre-processor chain. Restores
+                // whatever was on the slot before this test installed (almost
+                // always `undefined`) so back-to-back tests in the same worker
+                // don't see the prior test's `browserContext` leak.
+                if (preProcessors.length > 0) {
+                    g[global_names_1.HEAL_PREPROCESS] = previousPreprocess;
+                }
                 const capturedStdout = stdoutSession.stop();
                 stopScreenshots();
+                // Stop sidecar capture BEFORE finalizing the projector. Order:
+                //   1. restore the Browser patches so any post-teardown code
+                //      paths (e.g. Playwright internal cleanup) see a clean
+                //      newContext/newPage;
+                //   2. close the console session (no async work to drain);
+                //   3. drain + close the network session, passing the test's
+                //      final status so 'on-error' bodies are flushed only
+                //      when relevant. Network last so any in-flight response
+                //      that fires during teardown still lands in the file.
+                if (restoreWiring) {
+                    try {
+                        restoreWiring();
+                    }
+                    catch (err) {
+                        logger_1.log.error('wireAllPages.restore failed', err);
+                    }
+                }
+                if (consoleSession) {
+                    try {
+                        await (0, with_timeout_1.withTimeout)(consoleSession.close(), lifecycleTimeoutMs, 'console.close');
+                    }
+                    catch (err) {
+                        logger_1.log.error('console.close did not finish', err);
+                    }
+                }
+                if (networkSession) {
+                    const failed = (testInfo.status ?? 'passed') !== 'passed';
+                    try {
+                        await (0, with_timeout_1.withTimeout)(networkSession.stop(failed), lifecycleTimeoutMs, 'network.stop');
+                    }
+                    catch (err) {
+                        logger_1.log.error('network.stop did not finish', err);
+                    }
+                }
                 // Emit the final test-result record and close the output
                 // exporter chain (flushes NDJSON fd, awaits in-flight
                 // user-exporter I/O). The projector has its own `finalized`
@@ -216,12 +391,36 @@ exports.test = test_1.test.extend({
                 // shipped from here — their attachments are populated by
                 // Playwright in a later phase. Users who need them can
                 // register a Playwright reporter in their `playwright.config`.
-                await projector.finalize({
+                // Pass testInfo.errors[0] so any root statement whose __enter
+                // fired but whose __ok/__throw never did (Playwright aborted
+                // the hanging action on timeout before the catch block could
+                // run) gets flushed as `threw` with the test-level error.
+                const pendingError = testInfo.errors[0] ?? testInfo.error;
+                try {
+                    await (0, with_timeout_1.withTimeout)(projector.finalize({
+                        status: testInfo.status ?? 'passed',
+                        duration: testInfo.duration,
+                        stdout: capturedStdout.stdout.length ? capturedStdout.stdout : undefined,
+                        stderr: capturedStdout.stderr.length ? capturedStdout.stderr : undefined,
+                    }, pendingError), lifecycleTimeoutMs, 'projector.finalize');
+                }
+                catch (err) {
+                    // The trace may be truncated (final test-result record
+                    // and exporter close didn't complete in time) but the
+                    // test itself has already finished — keep going so
+                    // downstream registry cleanup still runs.
+                    logger_1.log.error('projector.finalize did not finish', err);
+                }
+                new artifact_summary_printer_1.ArtifactSummaryPrinter(testDir).print({
+                    title: testInfo.title,
                     status: testInfo.status ?? 'passed',
-                    duration: testInfo.duration,
-                    stdout: capturedStdout.stdout.length ? capturedStdout.stdout : undefined,
-                    stderr: capturedStdout.stderr.length ? capturedStdout.stderr : undefined,
                 });
+                // Registry cleanup is owned by `HealTracerReporter` — it
+                // runs on clean teardowns too because Playwright populates
+                // `result.attachments` only after this fixture's afterEach
+                // returns, so the reporter is the first hook with a final
+                // attachment list. It appends a `test-attachments` record
+                // and then deletes the registry entry.
             }
         },
         { auto: true },

package/dist/application/playwright-fixture/wire-all-pages.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 { APIRequest, APIRequestContext, Browser, BrowserContext, Page } from 'playwright';
+/**
+ * Capture sessions implement just enough of the `Wireable`
+ * surface for this helper. Both `NetworkCaptureSession` and
+ * `ConsoleCaptureSession` already match — the typing is structural
+ * to avoid an import cycle between the fixture and the adapters.
+ */
+export interface WireableContextSession {
+    attachToContext(ctx: BrowserContext): void;
+}
+export interface WireableApiSession {
+    attachToApiRequestContext?(api: APIRequestContext): void;
+}
+export type WireableSession = WireableContextSession & WireableApiSession;
+export interface WireAllPagesOptions {
+    browser: Browser;
+    /**
+     * Optional reference to the global `request` from `@playwright/test`
+     * (an `APIRequest`). Pass it to also patch `request.newContext` so
+     * api-request contexts created inside the test body are wired.
+     */
+    apiRequest?: APIRequest;
+}
+/** Returns a `restore()` thunk that undoes all patches. */
+export declare function wireAllPages(sessions: WireableSession[], opts: WireAllPagesOptions): () => void;
+/**
+ * Wire a single page (and its context) eagerly. Used by the fixture
+ * for the test's initial `page` so the first request fired by the
+ * test body is captured even if it races with the `attachToContext`
+ * call for a sibling context.
+ */
+export declare function wireInitialPage(sessions: WireableSession[], page: Page): void;