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

package/dist/infrastructure/playwright-locator-screenshot-adapter/screenshot-capture-session.js

@@ -41,16 +41,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScreenshotCaptureSession = void 0;
 // ScreenshotCaptureSession — one test's worth of locator-screenshot
 // capture: output directory, monotonic per-test sequence, CDP cache,
-// and the callback that stamps the filename onto the active
-// statement. The fixture creates one at test start and drops it at
+// the callback that stamps the filename onto the active statement,
+// and the best-effort timeout that caps every async the session
+// awaits. The fixture creates one at test start and drops it at
 // test teardown (via `setActiveCaptureSession`).
+//
+// One unified flow on every browser:
+//   1. (optional) `scrollIntoViewIfNeeded` — caller-controlled via
+//      `scrollBeforeCapture`. Locator actions always scroll (mirrors
+//      Playwright's own actionability auto-scroll). Locator assertions
+//      scroll too, except for `toBeInViewport` / `not.toBeInViewport`
+//      where the wrapper opts out so it doesn't change the assertion
+//      outcome.
+//   2. Measure the target's `boundingBox`.
+//   3. Inject a `<div>` overlay at the target's document position
+//      (4px magenta border + faint translucent fill). See
+//      `overlay-helpers.ts` for the page-side draw/remove pair.
+//   4. Take a viewport screenshot — via CDP `Page.captureScreenshot`
+//      when available (Chromium; avoids the headed-mode
+//      `Emulation.setDeviceMetricsOverride` resize that
+//      `page.screenshot` triggers), else `page.screenshot` fallback
+//      (Firefox/WebKit).
+//   5. Return a cleanup closure that removes the overlay after the
+//      caller's action/assertion completes.
+//
+// CDP `Overlay.highlightNode` is *not* used. It paints box-model
+// regions with colors and has no native "outline around the
+// element" mode, so the highlight is invisible on elements without
+// a CSS border at our chosen translucent alpha. Going through the
+// `<div>` overlay produces a visible frame on every browser without
+// caring about the element's CSS.
+//
+// Every async this session awaits is capped at `screenshotTimeoutMs`
+// — `scrollIntoViewIfNeeded`, `boundingBox`, every CDP `send`,
+// `newCDPSession`, the `page.screenshot` fallback, and the
+// overlay's `page.evaluate` (draw / remove). Decoration must
+// always fail-fast: the user's actionTimeout governs the action,
+// this timeout governs the tracer.
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const overlay_helpers_1 = require("./overlay-helpers");
+const with_timeout_1 = require("../../util/with-timeout");
+const logger_1 = require("../../util/logger");
 class ScreenshotCaptureSession {
-    constructor(outputDir, onScreenshotWritten) {
+    constructor(outputDir, onScreenshotWritten, screenshotTimeoutMs) {
         this.outputDir = outputDir;
         this.onScreenshotWritten = onScreenshotWritten;
+        this.screenshotTimeoutMs = screenshotTimeoutMs;
         this.seq = 0;
         // Per-page CDP session cache. `page.screenshot()` in headed mode forces
         // the configured viewport via `Emulation.setDeviceMetricsOverride`,
@@ -60,48 +97,79 @@ class ScreenshotCaptureSession {
         // retrying and fall back to `page.screenshot`.
         this.cdpSessionCache = new WeakMap();
     }
-    // Draw → screenshot → stamp. Returns the overlay node id if one is
-    // drawn (caller must call `removeOverlay` in finally), or null if
-    // nothing was drawn.
-    async captureWithHighlight(page, target, actionName) {
+    // Returns a cleanup closure to call after the action/assertion
+    // completes (caller invokes it in `finally`), or `null` if no
+    // cleanup is needed (capture-not-attempted cases).
+    async captureWithHighlight(page, target, actionName, options) {
+        if (options.scrollBeforeCapture && typeof target.scrollIntoViewIfNeeded === 'function') {
+            try {
+                await target.scrollIntoViewIfNeeded({ timeout: this.screenshotTimeoutMs });
+            }
+            catch (err) {
+                // Best-effort. If this fails, the target may be off-viewport
+                // in the screenshot — but Playwright's own actionability
+                // check still runs against the user's full actionTimeout
+                // when the action proceeds, so the test is unaffected.
+                logger_1.log.warn(`scrollIntoViewIfNeeded failed before ${actionName} screenshot`, err);
+            }
+        }
+        const box = await this.measureBox(target);
+        if (!box)
+            return null;
+        const seq = ++this.seq;
+        const filename = `highlight-${seq}-${actionName}.png`;
+        const fullPath = path.join(this.outputDir, filename);
+        return this.drawAndScreenshot(page, seq, box, filename, fullPath);
+    }
+    async measureBox(target) {
         if (typeof target.boundingBox !== 'function')
             return null;
-        let box;
         try {
-            box = await target.boundingBox();
+            return await target.boundingBox({ timeout: this.screenshotTimeoutMs });
         }
-        catch (_) {
+        catch (err) {
+            logger_1.log.warn('measureBox boundingBox threw — skipping highlight overlay', err);
             return null;
         }
-        if (!box)
-            return null;
-        const seq = ++this.seq;
+    }
+    async drawAndScreenshot(page, seq, box, filename, fullPath) {
         const nodeId = `_heal_draw_area_tracer_${seq}`;
         try {
-            await (0, overlay_helpers_1.drawOverlay)(page, nodeId, box);
+            await (0, overlay_helpers_1.drawOverlay)(page, nodeId, box, this.screenshotTimeoutMs);
         }
-        catch (_) {
+        catch (err) {
+            logger_1.log.warn('drawOverlay threw — skipping highlight screenshot', err);
             return null;
         }
         try {
-            const filename = `highlight-${seq}-${actionName}.png`;
-            const fullPath = path.join(this.outputDir, filename);
             await this.takeScreenshot(page, fullPath);
             this.onScreenshotWritten(filename);
         }
-        catch (_) {
-            // Overlay is drawn; caller must still clean it up in its finally.
+        catch (err) {
+            // Overlay drawn; the cleanup closure below still removes it.
+            logger_1.log.warn('takeScreenshot threw after overlay was drawn', err);
         }
-        return nodeId;
+        return () => (0, overlay_helpers_1.removeOverlay)(page, nodeId, this.screenshotTimeoutMs);
     }
     async takeScreenshot(page, fullPath) {
         const cdp = await this.getCDPSession(page);
         if (cdp) {
-            const { data } = await cdp.send('Page.captureScreenshot', { format: 'png' });
-            await fs.promises.writeFile(fullPath, Buffer.from(data, 'base64'));
+            const shotResp = (await this.cdpSend(cdp, 'Page.captureScreenshot', {
+                format: 'png',
+            }));
+            await fs.promises.writeFile(fullPath, Buffer.from(shotResp.data, 'base64'));
             return;
         }
-        await page.screenshot({ path: fullPath });
+        await page.screenshot({ path: fullPath, timeout: this.screenshotTimeoutMs });
+    }
+    // Promise.race wrapper around `cdp.send`. CDP itself has no
+    // protocol-level timeout; a wedged renderer or unhandled `alert()`
+    // would otherwise block forever. Returns `unknown` because
+    // CDPSession.send is overloaded per-command and cannot be wrapped
+    // generically without losing the per-command return shape — call
+    // sites that need typed fields cast.
+    cdpSend(cdp, method, params) {
+        return (0, with_timeout_1.withTimeout)(cdp.send.call(cdp, method, params), this.screenshotTimeoutMs, `cdp.send(${method})`);
     }
     async getCDPSession(page) {
         if (this.cdpSessionCache.has(page))
@@ -112,11 +180,12 @@ class ScreenshotCaptureSession {
                 this.cdpSessionCache.set(page, null);
                 return null;
             }
-            const session = await ctx.newCDPSession(page);
+            const session = await (0, with_timeout_1.withTimeout)(ctx.newCDPSession(page), this.screenshotTimeoutMs, 'newCDPSession');
             this.cdpSessionCache.set(page, session);
             return session;
         }
-        catch (_) {
+        catch (err) {
+            logger_1.log.warn('newCDPSession failed; falling back to page.screenshot for this page', err);
             this.cdpSessionCache.set(page, null);
             return null;
         }

package/dist/infrastructure/playwright-network-capture-adapter/body-preview.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { NetworkBodyPreview } from '../../domain/trace-event-recorder/model/network-trace-schema';
+export declare const DEFAULT_TEXTUAL_CONTENT_TYPES: readonly RegExp[];
+/**
+ * Decide whether a `Content-Type` header maps to a textual body that
+ * can be safely inlined as a UTF-8 preview. Anything else (images,
+ * video, octet-stream, application/zip) returns `false`.
+ *
+ * Allowlist may be `undefined` to mean "use defaults". An empty array
+ * means "no content type is allowed" — useful for users who want
+ * `bytes`-only records.
+ */
+export declare function isTextualContentType(contentType: string | undefined, allowlist: readonly RegExp[] | undefined): boolean;
+/**
+ * Trim a `Buffer` to at most `maxBytes` and decode as UTF-8 without
+ * cutting through a multi-byte codepoint. Walks back from the cap to
+ * the most recent leading byte, then keeps the codepoint only if all
+ * of its continuation bytes fall within the slice — otherwise the
+ * codepoint is dropped entirely. Avoids the `�` replacement
+ * characters Node would emit for a mid-codepoint cut.
+ */
+export declare function utf8SafeSlice(buf: Buffer, maxBytes: number): string;
+/**
+ * Build a `NetworkBodyPreview` from a `Buffer`. The buffer is
+ * truncated at `maxBodyBytes` if larger; `bytes` reports the total,
+ * `truncated` flips when the cap was hit, and `preview` carries the
+ * UTF-8 view (only when the content type was already deemed textual).
+ *
+ * `decodeAsText: false` means the caller already knows the body is
+ * binary and just wants size accounting — this returns the preview
+ * with `bytes` set and no `preview` string.
+ */
+export declare function previewBody(buf: Buffer, maxBodyBytes: number, decodeAsText: boolean): NetworkBodyPreview;
+/**
+ * Helper used by the adapter when only `Content-Length` is available
+ * (e.g. body capture is `'never'`). Records the size without ever
+ * reading the buffer.
+ */
+export declare function bytesOnlyPreview(bytes: number | undefined): NetworkBodyPreview | undefined;

package/dist/infrastructure/playwright-network-capture-adapter/body-preview.js

@@ -0,0 +1,107 @@
+"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.DEFAULT_TEXTUAL_CONTENT_TYPES = void 0;
+exports.isTextualContentType = isTextualContentType;
+exports.utf8SafeSlice = utf8SafeSlice;
+exports.previewBody = previewBody;
+exports.bytesOnlyPreview = bytesOnlyPreview;
+exports.DEFAULT_TEXTUAL_CONTENT_TYPES = Object.freeze([
+    /^text\//i,
+    /^application\/json\b/i,
+    /^application\/(?:[\w.+-]+\+)?xml\b/i,
+    /^application\/x-www-form-urlencoded\b/i,
+    /^application\/javascript\b/i,
+    /^application\/graphql\b/i,
+]);
+/**
+ * Decide whether a `Content-Type` header maps to a textual body that
+ * can be safely inlined as a UTF-8 preview. Anything else (images,
+ * video, octet-stream, application/zip) returns `false`.
+ *
+ * Allowlist may be `undefined` to mean "use defaults". An empty array
+ * means "no content type is allowed" — useful for users who want
+ * `bytes`-only records.
+ */
+function isTextualContentType(contentType, allowlist) {
+    if (!contentType)
+        return false;
+    const list = allowlist ?? exports.DEFAULT_TEXTUAL_CONTENT_TYPES;
+    return list.some((re) => re.test(contentType));
+}
+/**
+ * Trim a `Buffer` to at most `maxBytes` and decode as UTF-8 without
+ * cutting through a multi-byte codepoint. Walks back from the cap to
+ * the most recent leading byte, then keeps the codepoint only if all
+ * of its continuation bytes fall within the slice — otherwise the
+ * codepoint is dropped entirely. Avoids the `�` replacement
+ * characters Node would emit for a mid-codepoint cut.
+ */
+function utf8SafeSlice(buf, maxBytes) {
+    const end = Math.min(buf.length, maxBytes);
+    if (end === 0)
+        return '';
+    // Walk back to the leading byte of the last codepoint touched by
+    // the slice. Continuation bytes have the bit pattern 10xxxxxx;
+    // every other top-2-bit pattern (00, 11) is a starter.
+    let leadingIdx = end - 1;
+    while (leadingIdx > 0 && (buf[leadingIdx] & 0xc0) === 0x80) {
+        leadingIdx--;
+    }
+    const leadingByte = buf[leadingIdx];
+    let codepointBytes;
+    if ((leadingByte & 0x80) === 0) {
+        codepointBytes = 1; // 0xxxxxxx — ASCII
+    }
+    else if ((leadingByte & 0xe0) === 0xc0) {
+        codepointBytes = 2; // 110xxxxx
+    }
+    else if ((leadingByte & 0xf0) === 0xe0) {
+        codepointBytes = 3; // 1110xxxx
+    }
+    else if ((leadingByte & 0xf8) === 0xf0) {
+        codepointBytes = 4; // 11110xxx
+    }
+    else {
+        codepointBytes = 1; // invalid leading byte; treat as one-byte unit
+    }
+    const codepointEnd = leadingIdx + codepointBytes;
+    // If the codepoint extends past our cap, drop it; otherwise keep
+    // every byte we have, which now includes a complete final codepoint.
+    const cut = codepointEnd <= end ? end : leadingIdx;
+    return buf.toString('utf8', 0, cut);
+}
+/**
+ * Build a `NetworkBodyPreview` from a `Buffer`. The buffer is
+ * truncated at `maxBodyBytes` if larger; `bytes` reports the total,
+ * `truncated` flips when the cap was hit, and `preview` carries the
+ * UTF-8 view (only when the content type was already deemed textual).
+ *
+ * `decodeAsText: false` means the caller already knows the body is
+ * binary and just wants size accounting — this returns the preview
+ * with `bytes` set and no `preview` string.
+ */
+function previewBody(buf, maxBodyBytes, decodeAsText) {
+    const bytes = buf.length;
+    const truncated = bytes > maxBodyBytes;
+    const preview = decodeAsText ? utf8SafeSlice(buf, maxBodyBytes) : undefined;
+    return {
+        bytes,
+        truncated,
+        ...(preview !== undefined ? { preview } : {}),
+    };
+}
+/**
+ * Helper used by the adapter when only `Content-Length` is available
+ * (e.g. body capture is `'never'`). Records the size without ever
+ * reading the buffer.
+ */
+function bytesOnlyPreview(bytes) {
+    if (bytes === undefined || Number.isNaN(bytes))
+        return undefined;
+    return { bytes, truncated: false };
+}

package/dist/infrastructure/playwright-network-capture-adapter/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { NetworkCaptureSession } from './network-capture-session';
+export type { NetworkCaptureDeps } from './network-capture-session';
+export { NetworkCoalescer } from './network-coalescer';
+export { redactHeaders, DEFAULT_REDACT_HEADERS } from './redaction';
+export { isTextualContentType, previewBody, utf8SafeSlice, DEFAULT_TEXTUAL_CONTENT_TYPES, } from './body-preview';

package/dist/infrastructure/playwright-network-capture-adapter/index.js

@@ -0,0 +1,27 @@
+"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.DEFAULT_TEXTUAL_CONTENT_TYPES = exports.utf8SafeSlice = exports.previewBody = exports.isTextualContentType = exports.DEFAULT_REDACT_HEADERS = exports.redactHeaders = exports.NetworkCoalescer = exports.NetworkCaptureSession = void 0;
+// Feature: network capture — sidecar NDJSON stream of one record per
+// HTTP exchange that fired during a test (browser-context traffic +
+// runner-side `playwright.request` traffic).
+//
+// Public surface is the `NetworkCaptureSession` class. The fixture
+// owns construction, attachment to BrowserContexts /
+// APIRequestContexts, and the `stop(testFailed)` call at teardown.
+var network_capture_session_1 = require("./network-capture-session");
+Object.defineProperty(exports, "NetworkCaptureSession", { enumerable: true, get: function () { return network_capture_session_1.NetworkCaptureSession; } });
+var network_coalescer_1 = require("./network-coalescer");
+Object.defineProperty(exports, "NetworkCoalescer", { enumerable: true, get: function () { return network_coalescer_1.NetworkCoalescer; } });
+var redaction_1 = require("./redaction");
+Object.defineProperty(exports, "redactHeaders", { enumerable: true, get: function () { return redaction_1.redactHeaders; } });
+Object.defineProperty(exports, "DEFAULT_REDACT_HEADERS", { enumerable: true, get: function () { return redaction_1.DEFAULT_REDACT_HEADERS; } });
+var body_preview_1 = require("./body-preview");
+Object.defineProperty(exports, "isTextualContentType", { enumerable: true, get: function () { return body_preview_1.isTextualContentType; } });
+Object.defineProperty(exports, "previewBody", { enumerable: true, get: function () { return body_preview_1.previewBody; } });
+Object.defineProperty(exports, "utf8SafeSlice", { enumerable: true, get: function () { return body_preview_1.utf8SafeSlice; } });
+Object.defineProperty(exports, "DEFAULT_TEXTUAL_CONTENT_TYPES", { enumerable: true, get: function () { return body_preview_1.DEFAULT_TEXTUAL_CONTENT_TYPES; } });

package/dist/infrastructure/playwright-network-capture-adapter/network-capture-session.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { APIRequestContext, BrowserContext } from 'playwright';
+import type { HealTracerNetworkConfig } from '../../application/heal-config/types';
+import type { Clock } from '../../domain/trace-event-recorder/port/clock';
+export interface NetworkCaptureDeps {
+    clock: Clock;
+    startedAt: number;
+    getCurrentStatementSeq: () => number | undefined;
+    getCurrentStepPath: () => string[] | undefined;
+}
+export declare class NetworkCaptureSession {
+    private readonly ndjsonPath;
+    private readonly deps;
+    private fd;
+    private closed;
+    private readonly contexts;
+    private readonly apiContexts;
+    private readonly apiPatches;
+    private apiCounter;
+    private readonly coalescer;
+    private readonly bufferedBodies;
+    private readonly bodyMode;
+    private readonly maxBodyBytes;
+    private readonly extraDenylist;
+    private readonly contentTypeAllowlist;
+    private readonly urlFilter;
+    constructor(ndjsonPath: string, deps: NetworkCaptureDeps, config: HealTracerNetworkConfig);
+    attachToContext(ctx: BrowserContext): void;
+    attachToApiRequestContext(api: APIRequestContext): void;
+    private beginApiRecord;
+    private completeApiRecord;
+    private failApiRecord;
+    private snapshotApiCorrelation;
+    private handleRequest;
+    private handleResponse;
+    private handleRequestFinished;
+    private handleRequestFailed;
+    private snapshotCorrelation;
+    private write;
+    /**
+     * Drain any pending exchanges (writing them as-is) and, when the
+     * test ended in a failing status and `bodyMode === 'on-error'`,
+     * flush buffered bodies as `network-body` records. Idempotent.
+     *
+     * The body is currently fully synchronous (every disk write is
+     * `fs.writeSync`); the `Promise<void>` return type is preserved so
+     * the fixture can await it under `withTimeout` exactly like
+     * `projector.finalize`.
+     */
+    stop(testFailed: boolean): Promise<void>;
+}