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

package/dist/infrastructure/playwright-console-capture-adapter/console-capture-session.js

@@ -0,0 +1,243 @@
+"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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleCaptureSession = void 0;
+// ConsoleCaptureSession — one test's worth of browser-console capture.
+//
+// Subscribes to `console` and `pageerror` on every page in every
+// BrowserContext we are wired to (initial context + popups + any
+// context the user opened via `browser.newContext()` in the test
+// body). Each event is serialized to a `ConsoleRecord` and appended
+// to the per-test `heal-console.ndjson` sidecar. Cross-link to the
+// statement stream is via `t` (ms since recorder.startedAt) and the
+// top-of-enter-stack `seq` snapshotted at emit time.
+//
+// Behaviour notes:
+//   - `attachToContext(ctx)` is idempotent. A `WeakSet` drops
+//     duplicate wiring when the initial page's context is also
+//     returned by `browser.contexts()`.
+//   - `console-message.args()` are best-effort: each handle is
+//     resolved with a small `withTimeout`; on timeout we keep the
+//     record but drop `args`. We never block a test on console arg
+//     resolution.
+//   - The fd is opened lazily on the first record so disabled tests
+//     do not write empty files.
+const fs = __importStar(require("fs"));
+const with_timeout_1 = require("../../util/with-timeout");
+const ARG_RESOLVE_TIMEOUT_MS = 250;
+const DEFAULT_MAX_ARG_BYTES = 4096;
+const DEFAULT_MAX_ARGS_PER_EVENT = 10;
+const ALLOWED_LEVELS = [
+    'log',
+    'info',
+    'warn',
+    'error',
+    'debug',
+    'trace',
+    'pageerror',
+];
+class ConsoleCaptureSession {
+    constructor(ndjsonPath, deps, config) {
+        this.ndjsonPath = ndjsonPath;
+        this.deps = deps;
+        this.closed = false;
+        this.contexts = new WeakSet();
+        this.pages = new WeakSet();
+        const requested = config.levels ?? ALLOWED_LEVELS;
+        this.levels = new Set(requested);
+        this.maxArgBytes = config.maxArgBytes ?? DEFAULT_MAX_ARG_BYTES;
+        this.maxArgsPerEvent = config.maxArgsPerEvent ?? DEFAULT_MAX_ARGS_PER_EVENT;
+    }
+    /**
+     * Wire `ctx` and every page already living on it. Idempotent. Also
+     * subscribes to future pages via `ctx.on('page')` so popups created
+     * later in the test body are covered.
+     */
+    attachToContext(ctx) {
+        if (this.closed || this.contexts.has(ctx))
+            return;
+        this.contexts.add(ctx);
+        for (const page of ctx.pages())
+            this.attachToPage(page);
+        ctx.on('page', (page) => this.attachToPage(page));
+    }
+    attachToPage(page) {
+        if (this.closed || this.pages.has(page))
+            return;
+        this.pages.add(page);
+        page.on('console', (msg) => this.handleConsole(page, msg));
+        page.on('pageerror', (err) => this.handlePageError(page, err));
+    }
+    async handleConsole(page, msg) {
+        if (this.closed)
+            return;
+        const level = mapConsoleType(msg.type());
+        if (!this.levels.has(level))
+            return;
+        const args = await this.resolveArgs(msg);
+        const loc = msg.location();
+        const record = {
+            kind: 'console',
+            t: this.deps.clock.now() - this.deps.startedAt,
+            level,
+            text: msg.text(),
+            ...(args !== undefined ? { args } : {}),
+            ...(loc.url || loc.lineNumber !== undefined
+                ? {
+                    location: {
+                        ...(loc.url ? { url: loc.url } : {}),
+                        ...(loc.lineNumber !== undefined ? { line: loc.lineNumber } : {}),
+                        ...(loc.columnNumber !== undefined ? { col: loc.columnNumber } : {}),
+                    },
+                }
+                : {}),
+            ...this.snapshotCorrelation(page, msg.page()?.mainFrame()?.url()),
+        };
+        this.write(record);
+    }
+    handlePageError(page, err) {
+        if (this.closed)
+            return;
+        if (!this.levels.has('pageerror'))
+            return;
+        const record = {
+            kind: 'console',
+            t: this.deps.clock.now() - this.deps.startedAt,
+            level: 'pageerror',
+            text: err.message,
+            ...(err.stack ? { stack: err.stack } : {}),
+            ...this.snapshotCorrelation(page),
+        };
+        this.write(record);
+    }
+    snapshotCorrelation(page, frameUrl) {
+        const out = {};
+        const seq = this.deps.getCurrentStatementSeq();
+        if (seq !== undefined)
+            out.statementSeq = seq;
+        const stepPath = this.deps.getCurrentStepPath();
+        if (stepPath)
+            out.stepPath = stepPath;
+        try {
+            const url = page.url();
+            if (url)
+                out.pageUrl = url;
+        }
+        catch {
+            // page may already be closed — ignore.
+        }
+        if (frameUrl)
+            out.frameUrl = frameUrl;
+        return out;
+    }
+    async resolveArgs(msg) {
+        const handles = msg.args();
+        if (handles.length === 0)
+            return undefined;
+        const trimmed = handles.slice(0, this.maxArgsPerEvent);
+        try {
+            const resolved = await Promise.all(trimmed.map((h) => this.resolveArg(h)));
+            return resolved;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resolveArg(handle) {
+        try {
+            const value = await (0, with_timeout_1.withTimeout)(Promise.resolve(handle.jsonValue()), ARG_RESOLVE_TIMEOUT_MS, 'console-arg.jsonValue');
+            return capArg(value, this.maxArgBytes);
+        }
+        catch {
+            return '<unserializable>';
+        }
+    }
+    write(record) {
+        if (this.closed)
+            return;
+        if (this.fd === undefined)
+            this.fd = fs.openSync(this.ndjsonPath, 'a');
+        fs.writeSync(this.fd, JSON.stringify(record) + '\n');
+    }
+    close() {
+        if (this.closed)
+            return Promise.resolve();
+        this.closed = true;
+        if (this.fd !== undefined) {
+            try {
+                fs.closeSync(this.fd);
+            }
+            catch {
+                // best-effort; fd may already be gone.
+            }
+            this.fd = undefined;
+        }
+        return Promise.resolve();
+    }
+}
+exports.ConsoleCaptureSession = ConsoleCaptureSession;
+function mapConsoleType(type) {
+    switch (type) {
+        case 'log':
+        case 'info':
+        case 'warn':
+        case 'error':
+        case 'debug':
+        case 'trace':
+            return type;
+        case 'warning':
+            return 'warn';
+        default:
+            return 'log';
+    }
+}
+/**
+ * Defensive cap on arg payload size — strings that exceed the byte
+ * budget are sliced to `maxArgBytes` UTF-8 characters; non-string
+ * values pass through unchanged (they will be re-encoded by the
+ * NDJSON `JSON.stringify` and the natural JSON size is acceptable).
+ */
+function capArg(value, maxArgBytes) {
+    if (typeof value !== 'string')
+        return value;
+    if (Buffer.byteLength(value, 'utf8') <= maxArgBytes)
+        return value;
+    return value.slice(0, maxArgBytes) + '…';
+}

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

@@ -0,0 +1,7 @@
+/**
+ * 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 { ConsoleCaptureSession } from './console-capture-session';
+export type { ConsoleCaptureDeps } from './console-capture-session';

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

@@ -0,0 +1,20 @@
+"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.ConsoleCaptureSession = void 0;
+// Feature: console capture — sidecar NDJSON stream of every browser
+// `console.*` and `pageerror` event fired during a test.
+//
+// Public API:
+//   startConsoleCapture(initialContext, ndjsonPath, deps, config)
+//     Builds a `ConsoleCaptureSession`, wires the initial
+//     BrowserContext, and returns the session so the caller can wire
+//     additional contexts later (popups created via
+//     `browser.newContext()` in the test body) and call
+//     `close()` at teardown.
+var console_capture_session_1 = require("./console-capture-session");
+Object.defineProperty(exports, "ConsoleCaptureSession", { enumerable: true, get: function () { return console_capture_session_1.ConsoleCaptureSession; } });

package/dist/infrastructure/playwright-locator-screenshot-adapter/assertion-wrapper.js

@@ -6,8 +6,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapExpect = wrapExpect;
-const overlay_helpers_1 = require("./overlay-helpers");
 const locator_patch_1 = require("./locator-patch");
+const logger_1 = require("../../util/logger");
 // Duck-type: a Playwright Locator always has both `.boundingBox` and
 // `.page` as functions. FrameLocator / ElementHandle / Page won't match.
 // We don't use `instanceof` because the Locator class is created lazily
@@ -38,26 +38,38 @@ function wrapAssertion(assertion, locator) {
                     const page = typeof locator.page === 'function'
                         ? locator.page()
                         : null;
-                    let drawnNodeId = null;
+                    let cleanup = null;
                     const session = (0, locator_patch_1.getActiveCaptureSession)();
                     if (page && session) {
                         try {
-                            drawnNodeId = await session.captureWithHighlight(page, locator, `assert-${prop}`);
+                            // Scroll the target into view before the screenshot —
+                            // mirrors what locator actions already do — except for
+                            // `toBeInViewport()` / `not.toBeInViewport()`, which
+                            // are the only assertions whose outcome depends on
+                            // viewport position. For those we leave scroll alone so
+                            // we don't change what the user is asserting.
+                            const scrollBeforeCapture = prop !== 'toBeInViewport';
+                            cleanup = await session.captureWithHighlight(page, locator, `assert-${prop}`, {
+                                scrollBeforeCapture,
+                            });
                         }
-                        catch (_) {
+                        catch (err) {
                             // Capture is best-effort: never block the assertion.
+                            logger_1.log.warn(`captureWithHighlight rejected for assert-${String(prop)}`, err);
                         }
                     }
                     try {
                         return await value.apply(target, args);
                     }
                     finally {
-                        if (drawnNodeId && page) {
+                        if (cleanup) {
                             try {
-                                await (0, overlay_helpers_1.removeOverlay)(page, drawnNodeId);
+                                await cleanup();
                             }
-                            catch (_) {
-                                // Page gone — nothing to clean.
+                            catch (err) {
+                                // Cleanup is already capped via withTimeout inside
+                                // the session.
+                                logger_1.log.warn(`overlay cleanup rejected after assert-${String(prop)}`, err);
                             }
                         }
                     }
@@ -100,9 +112,10 @@ function wrapExpect(origExpect) {
         try {
             Object.defineProperty(wrapped, key, descriptor);
         }
-        catch (_) {
+        catch (err) {
             // Some descriptors may be non-configurable on the target; skip
             // them — the caller can still reach them via the original expect.
+            logger_1.log.warn(`could not copy expect.${String(key)} descriptor onto the wrapper`, err);
         }
     }
     return wrapped;

package/dist/infrastructure/playwright-locator-screenshot-adapter/index.d.ts

@@ -4,6 +4,6 @@
  * Please see the LICENSE file at the root of this repository
  */
 import type { Page } from 'playwright';
-export declare function startLocatorScreenshotCapture(samplePage: Page, outputDir: string, onScreenshotWritten: (filename: string) => void): () => void;
+export declare function startLocatorScreenshotCapture(samplePage: Page, outputDir: string, onScreenshotWritten: (filename: string) => void, screenshotTimeoutMs: number): () => void;
 export { wrapExpect } from './assertion-wrapper';
 export { ScreenshotCaptureSession } from './screenshot-capture-session';

package/dist/infrastructure/playwright-locator-screenshot-adapter/index.js

@@ -9,9 +9,9 @@ exports.ScreenshotCaptureSession = exports.wrapExpect = void 0;
 exports.startLocatorScreenshotCapture = startLocatorScreenshotCapture;
 const locator_patch_1 = require("./locator-patch");
 const screenshot_capture_session_1 = require("./screenshot-capture-session");
-function startLocatorScreenshotCapture(samplePage, outputDir, onScreenshotWritten) {
+function startLocatorScreenshotCapture(samplePage, outputDir, onScreenshotWritten, screenshotTimeoutMs) {
     (0, locator_patch_1.ensureLocatorPrototypePatched)(samplePage);
-    const session = new screenshot_capture_session_1.ScreenshotCaptureSession(outputDir, onScreenshotWritten);
+    const session = new screenshot_capture_session_1.ScreenshotCaptureSession(outputDir, onScreenshotWritten, screenshotTimeoutMs);
     (0, locator_patch_1.setActiveCaptureSession)(session);
     return () => (0, locator_patch_1.setActiveCaptureSession)(null);
 }

package/dist/infrastructure/playwright-locator-screenshot-adapter/locator-patch.js

@@ -9,10 +9,18 @@ exports.HIGHLIGHTED_LOCATOR_ACTIONS = void 0;
 exports.setActiveCaptureSession = setActiveCaptureSession;
 exports.getActiveCaptureSession = getActiveCaptureSession;
 exports.ensureLocatorPrototypePatched = ensureLocatorPrototypePatched;
-const overlay_helpers_1 = require("./overlay-helpers");
+const logger_1 = require("../../util/logger");
 // Locator action methods that will be highlighted and screenshotted.
 // User-facing actions only — not queries, not waits, not assertions.
 // If Playwright adds new action methods, append them here.
+//
+// Deliberately excluded: `scrollIntoViewIfNeeded`. The capture
+// pipeline calls `target.scrollIntoViewIfNeeded()` itself before
+// every action screenshot (so off-viewport targets aren't framing
+// empty space); patching it here would cause infinite recursion
+// when our own pre-screenshot scroll re-entered the patched method.
+// The standalone scroll-action screenshot is also redundant given
+// every other action now scrolls-then-screenshots anyway.
 exports.HIGHLIGHTED_LOCATOR_ACTIONS = [
     'click',
     'dblclick',
@@ -32,7 +40,6 @@ exports.HIGHLIGHTED_LOCATOR_ACTIONS = [
     'selectText',
     'setInputFiles',
     'dragTo',
-    'scrollIntoViewIfNeeded',
 ];
 const PATCHED = Symbol.for('heal-playwright-tracer.locator-patched');
 // Active-session registry. The fixture sets this at test start and
@@ -60,17 +67,22 @@ function ensureLocatorPrototypePatched(samplePage) {
             const self = this;
             const pg = typeof self.page === 'function' ? self.page() : null;
             const session = activeSession;
-            const drawnNodeId = pg && session ? await session.captureWithHighlight(pg, self, name) : null;
+            const cleanup = pg && session
+                ? await session.captureWithHighlight(pg, self, name, { scrollBeforeCapture: true })
+                : null;
             try {
                 return await orig.apply(self, args);
             }
             finally {
-                if (drawnNodeId && pg) {
+                if (cleanup) {
                     try {
-                        await (0, overlay_helpers_1.removeOverlay)(pg, drawnNodeId);
+                        await cleanup();
                     }
-                    catch (_) {
-                        // Page closed / navigated / element detached — nothing to clean.
+                    catch (err) {
+                        // Cleanup is already wrapped in withTimeout inside the
+                        // session; a rejection here means the page closed,
+                        // navigated, or the renderer wedged past the cap.
+                        logger_1.log.warn(`overlay cleanup rejected after locator.${name}`, err);
                     }
                 }
             }

package/dist/infrastructure/playwright-locator-screenshot-adapter/overlay-helpers.d.ts

@@ -10,6 +10,6 @@ interface Box {
     width: number;
     height: number;
 }
-export declare function drawOverlay(page: Page, nodeId: string, box: Box): Promise<void>;
-export declare function removeOverlay(page: Page, nodeId: string): Promise<void>;
+export declare function drawOverlay(page: Page, nodeId: string, box: Box, timeoutMs: number): Promise<void>;
+export declare function removeOverlay(page: Page, nodeId: string, timeoutMs: number): Promise<void>;
 export {};

package/dist/infrastructure/playwright-locator-screenshot-adapter/overlay-helpers.js

@@ -7,11 +7,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.drawOverlay = drawOverlay;
 exports.removeOverlay = removeOverlay;
+const with_timeout_1 = require("../../util/with-timeout");
 const DRAW_BORDER_SIZE = 4;
-const DRAW_COLOR = 'magenta';
-async function drawOverlay(page, nodeId, box) {
-    await page.evaluate((params) => {
-        const node = document.createElement('canvas');
+const DRAW_BORDER_COLOR = 'magenta';
+// Near-invisible tint to match the CDP path's contentColor (a:0.08).
+// The visible highlight is the border; the fill is just enough to
+// keep the two paths visually aligned without obscuring the element.
+const DRAW_FILL_COLOR = 'rgba(255, 0, 255, 0.08)';
+async function drawOverlay(page, nodeId, box, timeoutMs) {
+    await (0, with_timeout_1.withTimeout)(page.evaluate((params) => {
+        const node = document.createElement('div');
         node.id = params.nodeId;
         node.style.pointerEvents = 'none';
         node.style.position = 'absolute';
@@ -19,15 +24,23 @@ async function drawOverlay(page, nodeId, box) {
         node.style.top = params.box.y + window.scrollY + 'px';
         node.style.width = params.box.width + 'px';
         node.style.height = params.box.height + 'px';
-        node.style.border = params.borderSize + 'px solid ' + params.color;
+        node.style.border = params.borderSize + 'px solid ' + params.borderColor;
+        node.style.backgroundColor = params.fillColor;
+        node.style.boxSizing = 'border-box';
         node.style.zIndex = '2147483647';
         document.body.appendChild(node);
-    }, { nodeId, box, borderSize: DRAW_BORDER_SIZE, color: DRAW_COLOR });
+    }, {
+        nodeId,
+        box,
+        borderSize: DRAW_BORDER_SIZE,
+        borderColor: DRAW_BORDER_COLOR,
+        fillColor: DRAW_FILL_COLOR,
+    }), timeoutMs, 'drawOverlay');
 }
-async function removeOverlay(page, nodeId) {
-    await page.evaluate((id) => {
+async function removeOverlay(page, nodeId, timeoutMs) {
+    await (0, with_timeout_1.withTimeout)(page.evaluate((id) => {
         const el = document.getElementById(id);
         if (el)
             el.remove();
-    }, nodeId);
+    }, nodeId), timeoutMs, 'removeOverlay');
 }

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

@@ -11,16 +11,27 @@ interface Box {
     height: number;
 }
 interface CapturableTarget {
-    boundingBox?: () => Promise<Box | null>;
+    boundingBox?: (options?: {
+        timeout?: number;
+    }) => Promise<Box | null>;
+    scrollIntoViewIfNeeded?: (options?: {
+        timeout?: number;
+    }) => Promise<void>;
 }
 export declare class ScreenshotCaptureSession {
     private readonly outputDir;
     private readonly onScreenshotWritten;
+    private readonly screenshotTimeoutMs;
     private seq;
     private readonly cdpSessionCache;
-    constructor(outputDir: string, onScreenshotWritten: (filename: string) => void);
-    captureWithHighlight(page: Page, target: CapturableTarget, actionName: string): Promise<string | null>;
+    constructor(outputDir: string, onScreenshotWritten: (filename: string) => void, screenshotTimeoutMs: number);
+    captureWithHighlight(page: Page, target: CapturableTarget, actionName: string, options: {
+        scrollBeforeCapture: boolean;
+    }): Promise<(() => Promise<void>) | null>;
+    private measureBox;
+    private drawAndScreenshot;
     private takeScreenshot;
+    private cdpSend;
     private getCDPSession;
 }
 export {};