@elliemae/smoked-suite 26.2.23 → 26.2.24

package/dist/cjs/heap-memory-profiler/index.js

@@ -0,0 +1,170 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var heap_memory_profiler_exports = {};
+__export(heap_memory_profiler_exports, {
+  HeapMemoryProfiler: () => HeapMemoryProfiler
+});
+module.exports = __toCommonJS(heap_memory_profiler_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_encw_heap_doctor = require("@elliemae/encw-heap-doctor");
+class HeapMemoryProfiler {
+  /**
+   * @param page      - The Playwright `Page` instance for the current test.
+   * @param 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();
+  // ─── 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 label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
+   *                Used as the filename prefix and as the Memento key.
+   * @returns 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.page);
+    await client.send("HeapProfiler.enable");
+    const chunks = [];
+    client.on(
+      "HeapProfiler.addHeapSnapshotChunk",
+      ({ chunk }) => {
+        chunks.push(chunk);
+      }
+    );
+    await client.send("HeapProfiler.takeHeapSnapshot", {
+      reportProgress: false
+    });
+    await client.send("HeapProfiler.disable");
+    await client.detach();
+    import_node_fs.default.mkdirSync(this.outputDir, { recursive: true });
+    const filePath = import_node_path.default.join(
+      this.outputDir,
+      `${label}-${Date.now()}.heapsnapshot`
+    );
+    import_node_fs.default.writeFileSync(filePath, chunks.join(""));
+    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 beforeLabel - Label passed to {@link captureSnapshot} for the baseline.
+   * @param afterLabel  - Label passed to {@link captureSnapshot} for the post-flow snapshot.
+   * @param topN        - Override for the number of top leak groups in the report.
+   * @returns `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(beforeLabel, afterLabel, topN) {
+    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 import_encw_heap_doctor.HeapDoctor({ topN }).compare(before, after);
+    if (!result.ok) throw result.error;
+    import_node_fs.default.writeFileSync(
+      import_node_path.default.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 flow    - Async function containing the user actions to profile.
+   * @param options - {@link HeapProfilingOptions}
+   * @returns `ComparisonReport` on Chromium, `null` on all other browsers.
+   */
+  async withProfiling(flow, options = {}) {
+    const {
+      heapIterations = 1,
+      label = "flow",
+      topN,
+      failOnLeak = false,
+      leakThresholdBytes = 0
+    } = options;
+    if (!this.isChromium()) {
+      for (let i = 0; i < heapIterations; i++) await flow();
+      return null;
+    }
+    await this.captureSnapshot(`${label}-before`);
+    for (let i = 0; i < heapIterations; i++) await flow();
+    await this.captureSnapshot(`${label}-after`);
+    const report = await this.compare(
+      `${label}-before`,
+      `${label}-after`,
+      topN
+    );
+    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();
+  }
+}

package/dist/cjs/index.js

@@ -31,6 +31,7 @@ __export(index_exports, {
   AuthManager: () => import_auth.AuthManager,
   BasePage: () => import_base_page.BasePage,
   BaseTest: () => import_base_test.BaseTest,
+  HeapMemoryProfiler: () => import_heap_memory_profiler.HeapMemoryProfiler,
   PageSetup: () => import_page_setup.PageSetup,
   createBrowserStackConfig: () => import_browserstack.createBrowserStackConfig,
   createPlaywrightConfig: () => import_playwright_config.createPlaywrightConfig,
@@ -40,6 +41,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_base_test = require("./base-test/index.js");
+var import_heap_memory_profiler = require("./heap-memory-profiler/index.js");
 var import_base_page = require("./base-page/index.js");
 var import_auth = require("./auth/index.js");
 var import_page_setup = require("./page-setup/index.js");

package/dist/esm/heap-memory-profiler/index.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { HeapDoctor } from "@elliemae/encw-heap-doctor";
+class HeapMemoryProfiler {
+  /**
+   * @param page      - The Playwright `Page` instance for the current test.
+   * @param 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();
+  // ─── 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 label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
+   *                Used as the filename prefix and as the Memento key.
+   * @returns 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.page);
+    await client.send("HeapProfiler.enable");
+    const chunks = [];
+    client.on(
+      "HeapProfiler.addHeapSnapshotChunk",
+      ({ chunk }) => {
+        chunks.push(chunk);
+      }
+    );
+    await client.send("HeapProfiler.takeHeapSnapshot", {
+      reportProgress: false
+    });
+    await client.send("HeapProfiler.disable");
+    await client.detach();
+    fs.mkdirSync(this.outputDir, { recursive: true });
+    const filePath = path.join(
+      this.outputDir,
+      `${label}-${Date.now()}.heapsnapshot`
+    );
+    fs.writeFileSync(filePath, chunks.join(""));
+    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 beforeLabel - Label passed to {@link captureSnapshot} for the baseline.
+   * @param afterLabel  - Label passed to {@link captureSnapshot} for the post-flow snapshot.
+   * @param topN        - Override for the number of top leak groups in the report.
+   * @returns `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(beforeLabel, afterLabel, topN) {
+    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 }).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 flow    - Async function containing the user actions to profile.
+   * @param options - {@link HeapProfilingOptions}
+   * @returns `ComparisonReport` on Chromium, `null` on all other browsers.
+   */
+  async withProfiling(flow, options = {}) {
+    const {
+      heapIterations = 1,
+      label = "flow",
+      topN,
+      failOnLeak = false,
+      leakThresholdBytes = 0
+    } = options;
+    if (!this.isChromium()) {
+      for (let i = 0; i < heapIterations; i++) await flow();
+      return null;
+    }
+    await this.captureSnapshot(`${label}-before`);
+    for (let i = 0; i < heapIterations; i++) await flow();
+    await this.captureSnapshot(`${label}-after`);
+    const report = await this.compare(
+      `${label}-before`,
+      `${label}-after`,
+      topN
+    );
+    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/index.js

@@ -1,4 +1,5 @@
 import { BaseTest } from "./base-test/index.js";
+import { HeapMemoryProfiler } from "./heap-memory-profiler/index.js";
 import { BasePage } from "./base-page/index.js";
 import { AuthManager } from "./auth/index.js";
 import { PageSetup } from "./page-setup/index.js";
@@ -13,6 +14,7 @@ export {
   AuthManager,
   BasePage,
   BaseTest,
+  HeapMemoryProfiler,
   PageSetup,
   createBrowserStackConfig,
   createPlaywrightConfig,

package/dist/types/lib/heap-memory-profiler/index.d.ts

@@ -0,0 +1,100 @@
+import type { Page } from '@playwright/test';
+import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
+import type { HeapProfilingOptions } from '../types.js';
+export type { HeapProfilingOptions };
+/**
+ * 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      - The Playwright `Page` instance for the current test.
+     * @param outputDir - Directory where `.heapsnapshot` and `.md` files are written.
+     *                    Created automatically if it does not exist.
+     */
+    constructor(page: Page, outputDir: string);
+    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 label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
+     *                Used as the filename prefix and as the Memento key.
+     * @returns 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 beforeLabel - Label passed to {@link captureSnapshot} for the baseline.
+     * @param afterLabel  - Label passed to {@link captureSnapshot} for the post-flow snapshot.
+     * @param topN        - Override for the number of top leak groups in the report.
+     * @returns `ComparisonReport`, or `null` on non-Chromium browsers.
+     * @throws If either label has no cached snapshot path.
+     * @throws If `HeapDoctor.compare` returns `ok: false`.
+     */
+    compare(beforeLabel: string, afterLabel: string, topN?: number): 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 flow    - Async function containing the user actions to profile.
+     * @param options - {@link HeapProfilingOptions}
+     * @returns `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/index.d.ts

@@ -1,4 +1,5 @@
 export { BaseTest } from './base-test/index.js';
+export { HeapMemoryProfiler } from './heap-memory-profiler/index.js';
 export { BasePage } from './base-page/index.js';
 export { AuthManager } from './auth/index.js';
 export { PageSetup } from './page-setup/index.js';
@@ -7,5 +8,6 @@ export { createPlaywrightConfig } from './playwright-config/index.js';
 export { default as globalSetup } from './global-setup/index.js';
 export { createBrowserStackConfig, writeBrowserStackConfig, } from './browserstack/index.js';
 export type { BrowserStackOptions, BrowserStackPlatform, } from './browserstack/index.js';
-export type { AppContext, ContextProvider, AuthState, GotoOptions, Credentials, SmokedSuiteConfig, } from './types.js';
+export type { AppContext, ContextProvider, AuthState, GotoOptions, Credentials, SmokedSuiteConfig, HeapProfilingOptions, } from './types.js';
+export type { ComparisonReport } from '@elliemae/encw-heap-doctor';
 export type { CoverageConfig } from './monocartCoverage/index.js';

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

@@ -34,6 +34,42 @@ export interface GotoOptions {
     /** Custom timeout */
     timeout?: number;
 }
+/**
+ * Options for {@link HeapMemoryProfiler.withProfiling}.
+ */
+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;
+}
 /**
  * Configuration for {@link createPlaywrightConfig}.
  */