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

package/dist/infrastructure/heal-reporter/index.js

@@ -0,0 +1,23 @@
+"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.FailingStatementFinder = exports.NdjsonTailInspector = exports.CrashErrorClassifier = exports.healPendingRegistryPath = exports.HEAL_PENDING_SUBDIR = exports.HealTracerReporter = void 0;
+const heal_tracer_reporter_1 = require("./heal-tracer-reporter");
+var heal_tracer_reporter_2 = require("./heal-tracer-reporter");
+Object.defineProperty(exports, "HealTracerReporter", { enumerable: true, get: function () { return heal_tracer_reporter_2.HealTracerReporter; } });
+Object.defineProperty(exports, "HEAL_PENDING_SUBDIR", { enumerable: true, get: function () { return heal_tracer_reporter_2.HEAL_PENDING_SUBDIR; } });
+Object.defineProperty(exports, "healPendingRegistryPath", { enumerable: true, get: function () { return heal_tracer_reporter_2.healPendingRegistryPath; } });
+var crash_error_classifier_1 = require("./crash-error-classifier");
+Object.defineProperty(exports, "CrashErrorClassifier", { enumerable: true, get: function () { return crash_error_classifier_1.CrashErrorClassifier; } });
+var ndjson_tail_inspector_1 = require("./ndjson-tail-inspector");
+Object.defineProperty(exports, "NdjsonTailInspector", { enumerable: true, get: function () { return ndjson_tail_inspector_1.NdjsonTailInspector; } });
+var failing_statement_finder_1 = require("./failing-statement-finder");
+Object.defineProperty(exports, "FailingStatementFinder", { enumerable: true, get: function () { return failing_statement_finder_1.FailingStatementFinder; } });
+// Default export so users can register the reporter with the terse
+// `reporter: [['@heal-dev/heal-playwright-tracer/reporter']]` form,
+// matching how Playwright's own reporters are distributed.
+exports.default = heal_tracer_reporter_1.HealTracerReporter;

package/dist/infrastructure/heal-reporter/ndjson-tail-inspector.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 declare class NdjsonTailInspector {
+    endsWithTestResult(filePath: string): boolean;
+}

package/dist/infrastructure/heal-reporter/ndjson-tail-inspector.js

@@ -0,0 +1,75 @@
+"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.NdjsonTailInspector = void 0;
+// Checks whether an on-disk `heal-traces.ndjson` already ends with a
+// `test-result` record. Used by `HealTracerReporter.onTestEnd` to
+// decide whether the fixture's own `projector.finalize(...)` reached
+// disk — if it did, the reporter is a no-op; if it didn't, it
+// appends a synthetic `test-result` to terminate the file.
+//
+// Torn-write tolerance: a crash mid-`fs.writeSync` can leave a
+// partial JSON object on the last line. `JSON.parse` failures are
+// treated as "not terminated" — the reporter will then append its
+// own terminator, and consumers who encounter the torn line follow
+// the schema rule of discarding any trailing non-parseable line.
+const fs = __importStar(require("fs"));
+class NdjsonTailInspector {
+    endsWithTestResult(filePath) {
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            return false;
+        }
+        const lastLine = content.trimEnd().split('\n').at(-1) ?? '';
+        if (lastLine.length === 0)
+            return false;
+        try {
+            const parsed = JSON.parse(lastLine);
+            return parsed.kind === 'test-result';
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.NdjsonTailInspector = NdjsonTailInspector;

package/dist/infrastructure/heal-traces-layout/execution-id-resolver.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
+ */
+export type ExecutionIdSource = 'env' | 'generated';
+export declare const resolveExecutionId: () => string;
+export declare const getExecutionIdSource: () => ExecutionIdSource;
+/**
+ * Reset the memoized executionId. Test-only — production code never
+ * calls this. Allows unit tests to exercise both env-var and uuid
+ * fallback paths within the same process.
+ */
+export declare const resetExecutionIdForTesting: () => void;

package/dist/infrastructure/heal-traces-layout/execution-id-resolver.js

@@ -0,0 +1,52 @@
+"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.resetExecutionIdForTesting = exports.getExecutionIdSource = exports.resolveExecutionId = void 0;
+// Resolves the per-process executionId once and caches it.
+//
+// Source priority:
+//   1. process.env.HEAL_EXECUTION_ID (set this in CI to make every
+//      shard share a single id)
+//   2. randomUUID() — deterministic-enough fallback for local runs
+//
+// The result is memoized so repeat calls within a process return the
+// same value, and so multiple Playwright workers spawned by the same
+// runner all see one executionId per call (each worker is a separate
+// node process; the runner's env is inherited).
+const node_crypto_1 = require("node:crypto");
+let cached = null;
+const ENV_VAR = 'HEAL_EXECUTION_ID';
+const compute = () => {
+    const fromEnv = process.env[ENV_VAR];
+    if (fromEnv && fromEnv.length > 0) {
+        return { id: fromEnv, source: 'env' };
+    }
+    return { id: (0, node_crypto_1.randomUUID)(), source: 'generated' };
+};
+const resolveExecutionId = () => {
+    if (!cached) {
+        cached = compute();
+    }
+    return cached.id;
+};
+exports.resolveExecutionId = resolveExecutionId;
+const getExecutionIdSource = () => {
+    if (!cached) {
+        cached = compute();
+    }
+    return cached.source;
+};
+exports.getExecutionIdSource = getExecutionIdSource;
+/**
+ * Reset the memoized executionId. Test-only — production code never
+ * calls this. Allows unit tests to exercise both env-var and uuid
+ * fallback paths within the same process.
+ */
+const resetExecutionIdForTesting = () => {
+    cached = null;
+};
+exports.resetExecutionIdForTesting = resetExecutionIdForTesting;

package/dist/infrastructure/heal-traces-layout/heal-traces-layout.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
+ */
+export declare class HealTracesLayout {
+    readonly rootDir: string;
+    readonly executionId: string;
+    static readonly DIRNAME = "heal-traces";
+    static readonly NDJSON_FILENAME = "heal-traces.ndjson";
+    static readonly NETWORK_NDJSON_FILENAME = "heal-network.ndjson";
+    static readonly CONSOLE_NDJSON_FILENAME = "heal-console.ndjson";
+    static readonly TRACE_FILENAME = "trace.zip";
+    static readonly SCREENSHOTS_SUBDIR = "screenshots";
+    static readonly VIDEOS_SUBDIR = "videos";
+    static readonly EXECUTIONS_NDJSON = "executions.ndjson";
+    static readonly EXECUTION_MANIFEST = "execution.json";
+    constructor(rootDir: string, executionId: string);
+    healTracesRoot(): string;
+    executionDir(): string;
+    testDir(playwrightTestId: string, attempt: number): string;
+    ndjsonPath(playwrightTestId: string, attempt: number): string;
+    networkNdjsonPath(playwrightTestId: string, attempt: number): string;
+    consoleNdjsonPath(playwrightTestId: string, attempt: number): string;
+    tracePath(playwrightTestId: string, attempt: number): string;
+    screenshotPath(playwrightTestId: string, attempt: number, filename: string): string;
+    videoPath(playwrightTestId: string, attempt: number, filename: string): string;
+    /**
+     * Resolve a free-form relative path under the per-attempt directory
+     * (used for user attachments where preserving subdirs matters).
+     * Throws if `relPath` resolves outside the per-attempt root —
+     * guarding against path-traversal in attachment paths.
+     */
+    attachmentPath(playwrightTestId: string, attempt: number, relPath: string): string;
+    executionsNdjsonPath(): string;
+    executionManifestPath(): string;
+}

package/dist/infrastructure/heal-traces-layout/heal-traces-layout.js

@@ -0,0 +1,116 @@
+"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.HealTracesLayout = void 0;
+// Single source of truth for the persistent on-disk layout the tracer
+// produces under `<rootDir>/heal-traces/`:
+//
+//   <rootDir>/heal-traces/<executionId>/<playwrightTestId>/<attempt>/heal-traces.ndjson
+//   <rootDir>/heal-traces/<executionId>/<playwrightTestId>/<attempt>/trace.zip
+//   <rootDir>/heal-traces/<executionId>/<playwrightTestId>/<attempt>/screenshots/<file>
+//   <rootDir>/heal-traces/<executionId>/<playwrightTestId>/<attempt>/videos/<file>
+//
+// Pure path joins — no I/O, no fs.existsSync, no validation beyond
+// traversal-safety on user-supplied relative paths.
+const path = __importStar(require("path"));
+class HealTracesLayout {
+    constructor(rootDir, executionId) {
+        this.rootDir = rootDir;
+        this.executionId = executionId;
+    }
+    healTracesRoot() {
+        return path.join(this.rootDir, HealTracesLayout.DIRNAME);
+    }
+    executionDir() {
+        return path.join(this.healTracesRoot(), this.executionId);
+    }
+    testDir(playwrightTestId, attempt) {
+        return path.join(this.executionDir(), playwrightTestId, String(attempt));
+    }
+    ndjsonPath(playwrightTestId, attempt) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.NDJSON_FILENAME);
+    }
+    networkNdjsonPath(playwrightTestId, attempt) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.NETWORK_NDJSON_FILENAME);
+    }
+    consoleNdjsonPath(playwrightTestId, attempt) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.CONSOLE_NDJSON_FILENAME);
+    }
+    tracePath(playwrightTestId, attempt) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.TRACE_FILENAME);
+    }
+    screenshotPath(playwrightTestId, attempt, filename) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.SCREENSHOTS_SUBDIR, path.basename(filename));
+    }
+    videoPath(playwrightTestId, attempt, filename) {
+        return path.join(this.testDir(playwrightTestId, attempt), HealTracesLayout.VIDEOS_SUBDIR, path.basename(filename));
+    }
+    /**
+     * Resolve a free-form relative path under the per-attempt directory
+     * (used for user attachments where preserving subdirs matters).
+     * Throws if `relPath` resolves outside the per-attempt root —
+     * guarding against path-traversal in attachment paths.
+     */
+    attachmentPath(playwrightTestId, attempt, relPath) {
+        const root = this.testDir(playwrightTestId, attempt);
+        const resolved = path.resolve(root, relPath);
+        const rootResolved = path.resolve(root);
+        if (resolved !== rootResolved && !resolved.startsWith(rootResolved + path.sep)) {
+            throw new Error(`attachment path escapes test directory: ${relPath}`);
+        }
+        return resolved;
+    }
+    executionsNdjsonPath() {
+        return path.join(this.healTracesRoot(), HealTracesLayout.EXECUTIONS_NDJSON);
+    }
+    executionManifestPath() {
+        return path.join(this.executionDir(), HealTracesLayout.EXECUTION_MANIFEST);
+    }
+}
+exports.HealTracesLayout = HealTracesLayout;
+HealTracesLayout.DIRNAME = 'heal-traces';
+HealTracesLayout.NDJSON_FILENAME = 'heal-traces.ndjson';
+HealTracesLayout.NETWORK_NDJSON_FILENAME = 'heal-network.ndjson';
+HealTracesLayout.CONSOLE_NDJSON_FILENAME = 'heal-console.ndjson';
+HealTracesLayout.TRACE_FILENAME = 'trace.zip';
+HealTracesLayout.SCREENSHOTS_SUBDIR = 'screenshots';
+HealTracesLayout.VIDEOS_SUBDIR = 'videos';
+HealTracesLayout.EXECUTIONS_NDJSON = 'executions.ndjson';
+HealTracesLayout.EXECUTION_MANIFEST = 'execution.json';

package/dist/infrastructure/heal-traces-layout/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 { HealTracesLayout } from './heal-traces-layout';
+export { resolveExecutionId, getExecutionIdSource, resetExecutionIdForTesting, type ExecutionIdSource, } from './execution-id-resolver';

package/dist/infrastructure/heal-traces-layout/index.js

@@ -0,0 +1,14 @@
+"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.resetExecutionIdForTesting = exports.getExecutionIdSource = exports.resolveExecutionId = exports.HealTracesLayout = void 0;
+var heal_traces_layout_1 = require("./heal-traces-layout");
+Object.defineProperty(exports, "HealTracesLayout", { enumerable: true, get: function () { return heal_traces_layout_1.HealTracesLayout; } });
+var execution_id_resolver_1 = require("./execution-id-resolver");
+Object.defineProperty(exports, "resolveExecutionId", { enumerable: true, get: function () { return execution_id_resolver_1.resolveExecutionId; } });
+Object.defineProperty(exports, "getExecutionIdSource", { enumerable: true, get: function () { return execution_id_resolver_1.getExecutionIdSource; } });
+Object.defineProperty(exports, "resetExecutionIdForTesting", { enumerable: true, get: function () { return execution_id_resolver_1.resetExecutionIdForTesting; } });

package/dist/infrastructure/local-viewer-adapter/discover-traces.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 TestAttachment } from '../../domain/trace-event-recorder/model/statement-trace-schema';
+import type { ExecutionRecord, TestStatus } from '../../domain/persistence';
+export interface ExecutionSummary {
+    executionId: string;
+    source?: 'env' | 'generated';
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    totals?: ExecutionRecord['totals'];
+    git?: ExecutionRecord['git'];
+    playwrightVersion?: string;
+}
+export interface TestSummary {
+    /**
+     * Compound routing key for `/api/.../tests/:playwrightTestId/:attempt`.
+     * Format: `${playwrightTestId}_${attempt}` — the SPA splits on the
+     * last underscore. Sanitized — never contains `..`, `/`, or `\`.
+     */
+    id: string;
+    /** Underlying Playwright `testInfo.testId`. */
+    playwrightTestId: string;
+    /** 1-indexed attempt number. */
+    attempt: number;
+    /** NDJSON path relative to `<rootDir>/heal-traces/<executionId>/`. */
+    ndjsonPath: string;
+    title: string;
+    titlePath: string[];
+    file: string;
+    project: string;
+    status: TestStatus;
+    duration: number;
+    startedAt: number;
+    /**
+     * All Playwright attachments for this test. Sourced from the
+     * NDJSON's `test-attachments` record. Empty when the reporter
+     * isn't registered. Videos are NOT separately exposed — consumers
+     * filter on `contentType.startsWith('video/')` to derive them.
+     */
+    attachments: TestAttachment[];
+}
+export interface ViewerIndex {
+    schemaVersion: number;
+    executionId: string;
+    tests: TestSummary[];
+}
+/**
+ * Decode the compound id back into (playwrightTestId, attempt). Splits
+ * on the LAST underscore so test ids that themselves contain underscores
+ * round-trip correctly. Returns null on invalid shapes.
+ */
+export declare const parseSummaryId: (id: string) => {
+    playwrightTestId: string;
+    attempt: number;
+} | null;
+export declare const discoverTraces: (rootDir: string, executionId: string) => Promise<TestSummary[]>;
+export declare const buildIndex: (executionId: string, tests: TestSummary[]) => ViewerIndex;
+/**
+ * List executions known under `<rootDir>/heal-traces/`. Tries to read
+ * `executions.ndjson` first; if absent or partial, falls back to
+ * scanning subdirectory names. The index file lists records in the
+ * order runs were appended; we surface them newest-first to match
+ * the typical viewer use ("show me the latest run").
+ */
+export declare const discoverExecutions: (rootDir: string) => Promise<ExecutionSummary[]>;
+export declare const isSafeIdForRouting: (id: string) => boolean;