@elliemae/encw-leak-runner 1.0.13 → 1.0.15

package/dist/cjs/scenarios/pipeline/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pipeline_exports = {};
+__export(pipeline_exports, {
+  pipelineScenarioGroup: () => pipelineScenarioGroup
+});
+module.exports = __toCommonJS(pipeline_exports);
+var import_pipeline_task_navigation_scenario = require("./pipeline-task-navigation.scenario.js");
+const pipelineScenarios = [
+  import_pipeline_task_navigation_scenario.pipelineTaskNavigationScenario
+];
+const pipelineScenarioGroup = {
+  microapp: "pipeline",
+  scenarios: pipelineScenarios
+};

package/dist/cjs/scenarios/pipeline/page-models/PipelinePageModel.js

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var PipelinePageModel_exports = {};
+__export(PipelinePageModel_exports, {
+  PipelinePageModel: () => PipelinePageModel
+});
+module.exports = __toCommonJS(PipelinePageModel_exports);
+class PipelinePageModel {
+  constructor(page) {
+    this.page = page;
+  }
+  page;
+  static IFRAME_SELECTOR = '[data-testid="pui-iframe-container-pipelineui"]';
+  static TASKS_IFRAME_SELECTOR = '[data-testid="pui-iframe-container-taskspipeline"]';
+  static SPINNER_TEST_ID = "ds-circularindeterminateindicator-svg";
+  async waitForPipelineReady() {
+    await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
+  }
+  async clickTasksTab() {
+    await this.page.getByRole("tab", { name: "Tasks" }).click();
+  }
+  async clickPipelineTab() {
+    await this.page.getByRole("tab", { name: "Loans" }).click();
+  }
+  async waitForPipelineSpinner() {
+    await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
+  }
+  async waitForTasksReady() {
+    await this.page.locator(PipelinePageModel.TASKS_IFRAME_SELECTOR).contentFrame().getByTestId("circular-indicator").waitFor({ state: "hidden" });
+  }
+  async #waitForSpinner(iframeSelector) {
+    const spinner = this.page.frameLocator(iframeSelector).getByTestId(PipelinePageModel.SPINNER_TEST_ID);
+    await spinner.waitFor({ state: "visible" });
+    await spinner.waitFor({ state: "hidden" });
+  }
+}

package/dist/cjs/scenarios/pipeline/page-models/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var page_models_exports = {};
+__export(page_models_exports, {
+  PipelinePageModel: () => import_PipelinePageModel.PipelinePageModel
+});
+module.exports = __toCommonJS(page_models_exports);
+var import_PipelinePageModel = require("./PipelinePageModel.js");

package/dist/cjs/scenarios/pipeline/pipeline-task-navigation.scenario.js

@@ -0,0 +1,56 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pipeline_task_navigation_scenario_exports = {};
+__export(pipeline_task_navigation_scenario_exports, {
+  pipelineTaskNavigationScenario: () => pipelineTaskNavigationScenario
+});
+module.exports = __toCommonJS(pipeline_task_navigation_scenario_exports);
+var import_page_models = require("../one-admin/page-models/index.js");
+var import_page_models2 = require("./page-models/index.js");
+const pipelineTaskNavigationScenario = {
+  id: "pipeline-task-navigation",
+  name: "Pipeline Task Navigation",
+  description: "Navigate to pipeline task details and come back - verify iframe GC",
+  tags: ["critical"],
+  microappSelector: import_page_models2.PipelinePageModel.IFRAME_SELECTOR,
+  url: () => "/pipeline",
+  async setup(page) {
+    await import_page_models.AdminLandingPageModel.acceptCookiesIfShown(page);
+    const pipeline = new import_page_models2.PipelinePageModel(page);
+    await pipeline.waitForPipelineReady();
+  },
+  async action(page) {
+    const pipeline = new import_page_models2.PipelinePageModel(page);
+    const path = new URL(page.url()).pathname.replace(/\/$/, "");
+    if (path === "/pipeline") {
+      await pipeline.clickTasksTab();
+    }
+    await pipeline.waitForTasksReady();
+  },
+  async back(page) {
+    const pipeline = new import_page_models2.PipelinePageModel(page);
+    await pipeline.clickPipelineTab();
+    await pipeline.waitForPipelineSpinner();
+  },
+  repeat: () => 1,
+  thresholds: {
+    maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
+    maxNewLeakGroups: 0
+  }
+};

package/dist/esm/browser/heapMemoryProfiler.js

@@ -0,0 +1,152 @@
+import fs from "node:fs";
+import path from "node:path";
+import { HeapDoctor } from "@elliemae/encw-heap-doctor";
+class HeapMemoryProfiler {
+  /**
+   * @param {Page} page      - The Playwright `Page` instance for the current test.
+   * @param {string} outputDir - Directory where `.heapsnapshot` and `.md` files are written.
+   *                    Created automatically if it does not exist.
+   */
+  constructor(page, outputDir) {
+    this.page = page;
+    this.outputDir = outputDir;
+  }
+  page;
+  outputDir;
+  /** Memento store: maps snapshot label → absolute file path on disk. */
+  snapshots = /* @__PURE__ */ new Map();
+  getCDPTarget() {
+    return this.page;
+  }
+  // ─── Browser guard ──────────────────────────────────────────────────────────
+  isChromium() {
+    return this.page.context().browser()?.browserType().name() === "chromium";
+  }
+  // ─── Public API ─────────────────────────────────────────────────────────────
+  /**
+   * Capture a Chrome heap snapshot via CDP and persist it to disk.
+   *
+   * The snapshot is streamed in chunks via `HeapProfiler.addHeapSnapshotChunk`,
+   * joined, and written as a single `.heapsnapshot` file. The file path is cached
+   * internally under `label` so {@link compare} can resolve it by name.
+   * @param {string} label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
+   *                Used as the filename prefix and as the Memento key.
+   * @returns {Promise<string>} Absolute path to the written file, or `''` on non-Chromium browsers.
+   */
+  async captureSnapshot(label) {
+    if (!this.isChromium()) return "";
+    const client = await this.page.context().newCDPSession(this.getCDPTarget());
+    await client.send("HeapProfiler.enable");
+    fs.mkdirSync(this.outputDir, { recursive: true });
+    const filePath = path.join(
+      this.outputDir,
+      `${label}-${Date.now()}.heapsnapshot`
+    );
+    const writeStream = fs.createWriteStream(filePath);
+    client.on(
+      "HeapProfiler.addHeapSnapshotChunk",
+      ({ chunk }) => {
+        writeStream.write(chunk);
+      }
+    );
+    await client.send("HeapProfiler.takeHeapSnapshot", {
+      reportProgress: false
+    });
+    await client.send("HeapProfiler.disable");
+    await client.detach();
+    await new Promise((resolve, reject) => {
+      writeStream.end((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+    this.snapshots.set(label, filePath);
+    return filePath;
+  }
+  /**
+   * Compare two previously captured snapshots by their labels.
+   *
+   * Runs `HeapDoctor.compare()` on the resolved file paths and writes a
+   * markdown report to {@link outputDir}.
+   * @param {CompareParams} params - {@link CompareParams}
+   * @returns {Promise<ComparisonReport | null>} `ComparisonReport`, or `null` on non-Chromium browsers.
+   * @throws If either label has no cached snapshot path.
+   * @throws If `HeapDoctor.compare` returns `ok: false`.
+   */
+  async compare(params) {
+    const { beforeLabel, afterLabel, topN, originAllowList } = params;
+    if (!this.isChromium()) return null;
+    const before = this.snapshots.get(beforeLabel);
+    const after = this.snapshots.get(afterLabel);
+    if (!before || !after) {
+      throw new Error(
+        `HeapMemoryProfiler: snapshot not found for labels "${beforeLabel}" / "${afterLabel}". Call captureSnapshot() before compare().`
+      );
+    }
+    const result = await new HeapDoctor({ topN, originAllowList }).compare(
+      before,
+      after
+    );
+    if (!result.ok) throw result.error;
+    fs.writeFileSync(
+      path.join(this.outputDir, `comparison-${Date.now()}.md`),
+      result.value.markdown
+    );
+    return result.value;
+  }
+  /**
+   * Orchestrate the full heap profiling sequence for a user flow.
+   *
+   * Sequence (Template Method):
+   * 1. Capture **before** snapshot
+   * 2. Execute `flow` exactly `heapIterations` times
+   * 3. Capture **after** snapshot
+   * 4. Run `HeapDoctor.compare` and write the markdown report
+   * 5. If `failOnLeak` is `true` and `retainedSizeDelta > leakThresholdBytes`, throw
+   *
+   * On non-Chromium browsers: `flow` still runs `heapIterations` times,
+   * no snapshots are taken, and `null` is returned.
+   * @param {() => Promise<void>} flow    - Async function containing the user actions to profile.
+   * @param {HeapProfilingOptions} [options] - {@link HeapProfilingOptions}
+   * @returns {Promise<ComparisonReport | null>} `ComparisonReport` on Chromium, `null` on all other browsers.
+   */
+  async withProfiling(flow, options = {}) {
+    const {
+      heapIterations = 1,
+      label = "flow",
+      topN,
+      failOnLeak = false,
+      leakThresholdBytes = 0,
+      originAllowList
+    } = options;
+    if (!this.isChromium()) {
+      for (let i = 0; i < heapIterations; i += 1) await flow();
+      return null;
+    }
+    await this.captureSnapshot(`${label}-before`);
+    for (let i = 0; i < heapIterations; i += 1) await flow();
+    await this.captureSnapshot(`${label}-after`);
+    const report = await this.compare({
+      beforeLabel: `${label}-before`,
+      afterLabel: `${label}-after`,
+      topN,
+      originAllowList
+    });
+    if (report && failOnLeak && report.delta.retainedSizeDelta > leakThresholdBytes) {
+      throw new Error(
+        `Memory leak detected: retained size grew by ${report.delta.retainedSizeDelta} bytes (threshold: ${leakThresholdBytes} bytes). New leak groups: ${report.delta.newLeakGroups.length}. See: ${this.outputDir}`
+      );
+    }
+    return report;
+  }
+  /**
+   * Clear the internal snapshot label cache.
+   * Call in `afterEach` to prevent snapshot paths bleeding across tests.
+   */
+  clearSnapshots() {
+    this.snapshots.clear();
+  }
+}
+export {
+  HeapMemoryProfiler
+};

package/dist/esm/browser/iframeHeapProfiler.js

@@ -1,4 +1,4 @@
-import { HeapMemoryProfiler } from "@elliemae/smoked-suite";
+import { HeapMemoryProfiler } from "./heapMemoryProfiler.js";
 class IframeHeapProfiler extends HeapMemoryProfiler {
   constructor(profiledPage, frame, outputDir) {
     super(profiledPage, outputDir);

package/dist/esm/index.js

@@ -2,6 +2,7 @@ import { DEFAULT_THRESHOLDS } from "./types/config.js";
 import { ScenarioRegistry } from "./registry/scenarioRegistry.js";
 import { BatchRunner } from "./runner/batchRunner.js";
 import { ScenarioRunner } from "./runner/scenarioRunner.js";
+import { HeapMemoryProfiler } from "./browser/heapMemoryProfiler.js";
 import { IframeHeapProfiler } from "./browser/iframeHeapProfiler.js";
 import { ThresholdEvaluator } from "./analysis/thresholdEvaluator.js";
 import { ConsoleReporter } from "./reporting/consoleReporter.js";
@@ -23,6 +24,7 @@ export {
   DEFAULT_THRESHOLDS,
   EnvVarConfigSource,
   FileConfigSource,
+  HeapMemoryProfiler,
   IframeHeapProfiler,
   JunitReporter,
   MissingRequiredParamError,

package/dist/esm/runner/scenarioRunner.js

@@ -68,11 +68,12 @@ class ScenarioRunner {
     await this.repeatScenarioActions(scenario, page, frame);
     await forceGarbageCollection(page);
     paths.after = await profiler.captureSnapshot("after");
-    const report = await profiler.compare(
-      "before",
-      "after",
-      this.config.runner.topN
-    );
+    const report = await profiler.compare({
+      beforeLabel: "before",
+      afterLabel: "after",
+      topN: this.config.runner.topN,
+      originAllowList: [new URL(this.config.env.baseUrl).origin]
+    });
     if (report) await this.writeReport(report, scenario);
     return report;
   }
@@ -88,7 +89,9 @@ class ScenarioRunner {
     });
     process.stderr.write(`[scenarioRunner] post-login URL = ${page.url()}
 `);
-    await page.waitForURL(`**${scenario.url()}**`, { timeout: 3e4 });
+    if (!page.url().includes(scenario.url())) {
+      await page.goto(scenario.url(), { waitUntil: "load", timeout: 3e4 });
+    }
     process.stderr.write(
       `[scenarioRunner] settled URL before iframe = ${page.url()}
 `

package/dist/esm/scenarios/index.js

@@ -1,9 +1,12 @@
 import { ScenarioRegistry } from "../registry/scenarioRegistry.js";
-import { oneAdminScenarios } from "./one-admin/index.js";
-const scenarioRegistry = new ScenarioRegistry().register({
-  microapp: "one-admin",
-  scenarios: oneAdminScenarios
-});
+import { oneAdminScenarioGroup } from "./one-admin/index.js";
+import { pipelineScenarioGroup } from "./pipeline/index.js";
+const scenarioRegistry = (() => {
+  const registry = new ScenarioRegistry();
+  registry.register(oneAdminScenarioGroup);
+  registry.register(pipelineScenarioGroup);
+  return registry;
+})();
 export {
   scenarioRegistry
 };

package/dist/esm/scenarios/one-admin/index.js

@@ -2,6 +2,10 @@ import { exportNavigationScenario } from "./export-navigation.scenario.js";
 const oneAdminScenarios = [
   exportNavigationScenario
 ];
+const oneAdminScenarioGroup = {
+  microapp: "one-admin",
+  scenarios: oneAdminScenarios
+};
 export {
-  oneAdminScenarios
+  oneAdminScenarioGroup
 };

package/dist/esm/scenarios/pipeline/index.js

@@ -0,0 +1,11 @@
+import { pipelineTaskNavigationScenario } from "./pipeline-task-navigation.scenario.js";
+const pipelineScenarios = [
+  pipelineTaskNavigationScenario
+];
+const pipelineScenarioGroup = {
+  microapp: "pipeline",
+  scenarios: pipelineScenarios
+};
+export {
+  pipelineScenarioGroup
+};

package/dist/esm/scenarios/pipeline/page-models/PipelinePageModel.js

@@ -0,0 +1,32 @@
+class PipelinePageModel {
+  constructor(page) {
+    this.page = page;
+  }
+  page;
+  static IFRAME_SELECTOR = '[data-testid="pui-iframe-container-pipelineui"]';
+  static TASKS_IFRAME_SELECTOR = '[data-testid="pui-iframe-container-taskspipeline"]';
+  static SPINNER_TEST_ID = "ds-circularindeterminateindicator-svg";
+  async waitForPipelineReady() {
+    await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
+  }
+  async clickTasksTab() {
+    await this.page.getByRole("tab", { name: "Tasks" }).click();
+  }
+  async clickPipelineTab() {
+    await this.page.getByRole("tab", { name: "Loans" }).click();
+  }
+  async waitForPipelineSpinner() {
+    await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
+  }
+  async waitForTasksReady() {
+    await this.page.locator(PipelinePageModel.TASKS_IFRAME_SELECTOR).contentFrame().getByTestId("circular-indicator").waitFor({ state: "hidden" });
+  }
+  async #waitForSpinner(iframeSelector) {
+    const spinner = this.page.frameLocator(iframeSelector).getByTestId(PipelinePageModel.SPINNER_TEST_ID);
+    await spinner.waitFor({ state: "visible" });
+    await spinner.waitFor({ state: "hidden" });
+  }
+}
+export {
+  PipelinePageModel
+};

package/dist/esm/scenarios/pipeline/page-models/index.js

@@ -0,0 +1,4 @@
+import { PipelinePageModel } from "./PipelinePageModel.js";
+export {
+  PipelinePageModel
+};

package/dist/esm/scenarios/pipeline/pipeline-task-navigation.scenario.js

@@ -0,0 +1,36 @@
+import { AdminLandingPageModel } from "../one-admin/page-models/index.js";
+import { PipelinePageModel } from "./page-models/index.js";
+const pipelineTaskNavigationScenario = {
+  id: "pipeline-task-navigation",
+  name: "Pipeline Task Navigation",
+  description: "Navigate to pipeline task details and come back - verify iframe GC",
+  tags: ["critical"],
+  microappSelector: PipelinePageModel.IFRAME_SELECTOR,
+  url: () => "/pipeline",
+  async setup(page) {
+    await AdminLandingPageModel.acceptCookiesIfShown(page);
+    const pipeline = new PipelinePageModel(page);
+    await pipeline.waitForPipelineReady();
+  },
+  async action(page) {
+    const pipeline = new PipelinePageModel(page);
+    const path = new URL(page.url()).pathname.replace(/\/$/, "");
+    if (path === "/pipeline") {
+      await pipeline.clickTasksTab();
+    }
+    await pipeline.waitForTasksReady();
+  },
+  async back(page) {
+    const pipeline = new PipelinePageModel(page);
+    await pipeline.clickPipelineTab();
+    await pipeline.waitForPipelineSpinner();
+  },
+  repeat: () => 1,
+  thresholds: {
+    maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
+    maxNewLeakGroups: 0
+  }
+};
+export {
+  pipelineTaskNavigationScenario
+};

package/dist/types/lib/browser/heapMemoryProfiler.d.ts

@@ -0,0 +1,149 @@
+import type { Page, Frame } from '@playwright/test';
+import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
+export interface HeapProfilingOptions {
+    /**
+     * Number of times to execute the flow between the before and after snapshots.
+     * More iterations amplify the leak signal — a leak of N bytes per run becomes
+     * N × heapIterations in the delta, making small leaks detectable above GC noise.
+     * Default: 1.
+     */
+    heapIterations?: number;
+    /**
+     * Label prefix used in snapshot filenames and as the Memento key.
+     * Two files are written: `<label>-before-<epoch>.heapsnapshot` and
+     * `<label>-after-<epoch>.heapsnapshot`.
+     * Default: 'flow'.
+     */
+    label?: string;
+    /**
+     * Number of top leak groups to include in the HeapDoctor report.
+     * Default: 5 (HeapDoctor default).
+     */
+    topN?: number;
+    /**
+     * When `true`, throws after comparison if `retainedSizeDelta` exceeds
+     * {@link leakThresholdBytes}, causing the Playwright test to fail.
+     * Default: false.
+     */
+    failOnLeak?: boolean;
+    /**
+     * Retained-size growth in bytes above which the test is failed when
+     * {@link failOnLeak} is `true`. Set to 0 to fail on any positive delta.
+     * Default: 0.
+     */
+    leakThresholdBytes?: number;
+    /**
+     * Optional allow-list of `Window` origins (e.g. `'https://encompass.q3.ice.com'`).
+     *
+     * Forwarded to `HeapDoctor`; suppresses retainer chains rooted in unrelated
+     * same-site iframes (e.g. partner plugins) that share the main V8 isolate.
+     * Chains with no `Window` step are always kept.
+     */
+    originAllowList?: readonly string[];
+}
+/** Parameters for {@link HeapMemoryProfiler.compare}. */
+export interface CompareParams {
+    /** Label passed to `captureSnapshot()` for the baseline. */
+    beforeLabel: string;
+    /** Label passed to `captureSnapshot()` for the post-flow snapshot. */
+    afterLabel: string;
+    /** Override for the number of top leak groups in the report. */
+    topN?: number;
+    /** Allow-list of `Window` origins; forwarded to `HeapDoctor`. */
+    originAllowList?: readonly string[];
+}
+/**
+ * Encapsulates heap memory profiling for a single Playwright test.
+ *
+ * **Responsibilities:**
+ * - CDP session lifecycle (open, stream chunks, detach)
+ * - `.heapsnapshot` file I/O
+ * - Snapshot label cache (Memento store, cleared per test)
+ * - HeapDoctor comparison and markdown report writing
+ * - Optional test failure on leak threshold breach
+ *
+ * **Usage:**
+ * ```ts
+ * class MySpec extends AdminBaseTest {
+ *   private heapProfiler!: HeapMemoryProfiler;
+ *
+ *   async beforeEach() {
+ *     await super.beforeEach();
+ *     this.heapProfiler = new HeapMemoryProfiler(this.page, 'reports/heap-snapshots/my-spec');
+ *   }
+ *
+ *   async afterEach() {
+ *     this.heapProfiler.clearSnapshots();
+ *     await super.afterEach();
+ *   }
+ *
+ *   async testFlow_Memory() {
+ *     await this.goto('some.route');
+ *     await this.heapProfiler.withProfiling(async () => {
+ *       await this.somePage.doSomething();
+ *     }, { heapIterations: 3, label: 'my-flow', failOnLeak: true, leakThresholdBytes: 500_000 });
+ *   }
+ * }
+ * ```
+ *
+ * **Non-Chromium:** All methods silently no-op and return `null` / empty string.
+ * The flow inside `withProfiling` still executes normally.
+ */
+export declare class HeapMemoryProfiler {
+    private readonly page;
+    private readonly outputDir;
+    /** Memento store: maps snapshot label → absolute file path on disk. */
+    private readonly snapshots;
+    /**
+     * @param {Page} page      - The Playwright `Page` instance for the current test.
+     * @param {string} outputDir - Directory where `.heapsnapshot` and `.md` files are written.
+     *                    Created automatically if it does not exist.
+     */
+    constructor(page: Page, outputDir: string);
+    protected getCDPTarget(): Page | Frame;
+    private isChromium;
+    /**
+     * Capture a Chrome heap snapshot via CDP and persist it to disk.
+     *
+     * The snapshot is streamed in chunks via `HeapProfiler.addHeapSnapshotChunk`,
+     * joined, and written as a single `.heapsnapshot` file. The file path is cached
+     * internally under `label` so {@link compare} can resolve it by name.
+     * @param {string} label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
+     *                Used as the filename prefix and as the Memento key.
+     * @returns {Promise<string>} Absolute path to the written file, or `''` on non-Chromium browsers.
+     */
+    captureSnapshot(label: string): Promise<string>;
+    /**
+     * Compare two previously captured snapshots by their labels.
+     *
+     * Runs `HeapDoctor.compare()` on the resolved file paths and writes a
+     * markdown report to {@link outputDir}.
+     * @param {CompareParams} params - {@link CompareParams}
+     * @returns {Promise<ComparisonReport | null>} `ComparisonReport`, or `null` on non-Chromium browsers.
+     * @throws If either label has no cached snapshot path.
+     * @throws If `HeapDoctor.compare` returns `ok: false`.
+     */
+    compare(params: CompareParams): Promise<ComparisonReport | null>;
+    /**
+     * Orchestrate the full heap profiling sequence for a user flow.
+     *
+     * Sequence (Template Method):
+     * 1. Capture **before** snapshot
+     * 2. Execute `flow` exactly `heapIterations` times
+     * 3. Capture **after** snapshot
+     * 4. Run `HeapDoctor.compare` and write the markdown report
+     * 5. If `failOnLeak` is `true` and `retainedSizeDelta > leakThresholdBytes`, throw
+     *
+     * On non-Chromium browsers: `flow` still runs `heapIterations` times,
+     * no snapshots are taken, and `null` is returned.
+     * @param {() => Promise<void>} flow    - Async function containing the user actions to profile.
+     * @param {HeapProfilingOptions} [options] - {@link HeapProfilingOptions}
+     * @returns {Promise<ComparisonReport | null>} `ComparisonReport` on Chromium, `null` on all other browsers.
+     */
+    withProfiling(flow: () => Promise<void>, options?: HeapProfilingOptions): Promise<ComparisonReport | null>;
+    /**
+     * Clear the internal snapshot label cache.
+     * Call in `afterEach` to prevent snapshot paths bleeding across tests.
+     */
+    clearSnapshots(): void;
+}

package/dist/types/lib/browser/iframeHeapProfiler.d.ts

@@ -1,5 +1,5 @@
-import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
 import type { Page, Frame } from '@playwright/test';
+import { HeapMemoryProfiler } from './heapMemoryProfiler.js';
 export declare class IframeHeapProfiler extends HeapMemoryProfiler {
     private readonly profiledPage;
     private readonly frame;

package/dist/types/lib/browser/tests/heapMemoryProfiler.test.d.ts

@@ -0,0 +1 @@
+export {};