@elliemae/encw-leak-runner 1.0.2

package/dist/esm/config/sources/fileConfigSource.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import {
+  runnerConfigFileSchema
+} from "../runnerConfigSchema.js";
+class FileConfigSource {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  filePath;
+  priority = 1;
+  name = "file";
+  load() {
+    if (!fs.existsSync(this.filePath)) return {};
+    const raw = fs.readFileSync(this.filePath, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse config file ${this.filePath}: ${err.message}`
+      );
+    }
+    const result = runnerConfigFileSchema.safeParse(parsed);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+      throw new Error(`Invalid config file ${this.filePath}:
+${issues}`);
+    }
+    return result.data;
+  }
+}
+export {
+  FileConfigSource
+};

package/dist/esm/index.js

@@ -0,0 +1,35 @@
+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 { IframeHeapProfiler } from "./browser/iframeHeapProfiler.js";
+import { ThresholdEvaluator } from "./analysis/thresholdEvaluator.js";
+import { ConsoleReporter } from "./reporting/consoleReporter.js";
+import { JunitReporter } from "./reporting/junitReporter.js";
+import { RunnerConfigLoader } from "./config/runnerConfigLoader.js";
+import { FileConfigSource } from "./config/sources/fileConfigSource.js";
+import { EnvVarConfigSource } from "./config/sources/envVarConfigSource.js";
+import { CliOverrideConfigSource } from "./config/sources/cliOverrideConfigSource.js";
+import {
+  RequiredEnvParamsResolver,
+  MissingRequiredParamError
+} from "./config/requiredEnvParams.js";
+import { buildProgram, defaultDeps } from "./cli/index.js";
+export {
+  BatchRunner,
+  CliOverrideConfigSource,
+  ConsoleReporter,
+  DEFAULT_THRESHOLDS,
+  EnvVarConfigSource,
+  FileConfigSource,
+  IframeHeapProfiler,
+  JunitReporter,
+  MissingRequiredParamError,
+  RequiredEnvParamsResolver,
+  RunnerConfigLoader,
+  ScenarioRegistry,
+  ScenarioRunner,
+  ThresholdEvaluator,
+  buildProgram,
+  defaultDeps
+};

package/dist/esm/package.json

@@ -0,0 +1,7 @@
+{
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/dist/esm/registry/scenarioRegistry.js

@@ -0,0 +1,31 @@
+class ScenarioRegistry {
+  entries = /* @__PURE__ */ new Map();
+  register(group) {
+    group.scenarios.forEach((scenario) => {
+      const key = `${group.microapp}/${scenario.id}`;
+      if (this.entries.has(key)) {
+        throw new Error(`Duplicate scenario: ${key}`);
+      }
+      this.entries.set(key, scenario);
+    });
+    return this;
+  }
+  get(key) {
+    return this.entries.get(key);
+  }
+  has(key) {
+    return this.entries.has(key);
+  }
+  size() {
+    return this.entries.size;
+  }
+  list() {
+    return Array.from(this.entries.entries()).map(([key, scenario]) => ({ key, scenario })).sort((a, b) => a.key.localeCompare(b.key));
+  }
+  filterByTag(tag) {
+    return this.list().filter((entry) => entry.scenario.tags?.includes(tag));
+  }
+}
+export {
+  ScenarioRegistry
+};

package/dist/esm/reporting/consoleReporter.js

@@ -0,0 +1,40 @@
+const GREEN = "\x1B[32m";
+const RED = "\x1B[31m";
+const BOLD = "\x1B[1m";
+const RESET = "\x1B[0m";
+function formatDuration(ms) {
+  return `${(ms / 1e3).toFixed(1)}s`;
+}
+function printLine(text) {
+  process.stdout.write(`${text}
+`);
+}
+function printScenario(result) {
+  const status = result.passed ? `${GREEN}PASSED${RESET}` : `${RED}FAILED${RESET}`;
+  const duration = formatDuration(result.durationMs);
+  printLine(`  ${status}  ${BOLD}${result.name}${RESET}  (${duration})`);
+  if (!result.passed && result.thresholdResult.reason) {
+    printLine(`         ${RED}\u2192 ${result.thresholdResult.reason}${RESET}`);
+  }
+  if (!result.passed && result.error) {
+    printLine(`         ${RED}\u2192 Error: ${result.error.message}${RESET}`);
+  }
+}
+class ConsoleReporter {
+  write(summary) {
+    printLine("");
+    printLine(`${BOLD}MEMORY LEAK RUN RESULTS${RESET}`);
+    printLine("\u2500".repeat(50));
+    summary.results.forEach(printScenario);
+    printLine("\u2500".repeat(50));
+    const total = summary.results.length;
+    const duration = formatDuration(summary.totalDurationMs);
+    printLine(
+      `${summary.passCount} passed, ${summary.failCount} failed of ${total} scenarios  (${duration})`
+    );
+    printLine("");
+  }
+}
+export {
+  ConsoleReporter
+};

package/dist/esm/reporting/junitReporter.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function formatSeconds(ms) {
+  return (ms / 1e3).toFixed(1);
+}
+function renderTestCase(result) {
+  const timeAttr = `time="${formatSeconds(result.durationMs)}"`;
+  const open = `    <testcase name="${escapeXml(
+    result.name
+  )}" classname="memory-leak" ${timeAttr}>`;
+  if (result.passed) {
+    return `${open}
+    </testcase>`;
+  }
+  const message = result.thresholdResult.reason ?? result.error?.message ?? "Unknown failure";
+  const body = result.thresholdResult.reason ? `See leak-reports/${result.name}.md for full analysis` : result.error?.stack ?? "";
+  return `${open}
+      <failure message="${escapeXml(message)}">
+        ${escapeXml(body)}
+      </failure>
+    </testcase>`;
+}
+class JunitReporter {
+  write(summary, outputDir) {
+    const totalTime = formatSeconds(summary.totalDurationMs);
+    const testCases = summary.results.map(renderTestCase).join("\n");
+    const xml = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      `<testsuites name="encw-leak-runner" time="${totalTime}">`,
+      `  <testsuite name="microapp-memory-leaks" tests="${summary.results.length}" failures="${summary.failCount}" time="${totalTime}">`,
+      testCases,
+      "  </testsuite>",
+      "</testsuites>"
+    ].join("\n");
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(path.join(outputDir, "test-results.xml"), xml, "utf8");
+    return Promise.resolve();
+  }
+}
+export {
+  JunitReporter
+};

package/dist/esm/runner/aiEnhancementStep.js

@@ -0,0 +1,22 @@
+import {
+  AiEnhancer,
+  renderComparisonMarkdown
+} from "@elliemae/encw-heap-doctor";
+async function enhanceMarkdownIfConfigured(report, config, scenarioName) {
+  if (!config.ai?.apiKey) return report.markdown;
+  try {
+    const enhancer = new AiEnhancer(config.ai);
+    await enhancer.enhance(report.afterAnalysis.leakResults);
+    return renderComparisonMarkdown(report);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `Genice enhancement failed for ${scenarioName}: ${message}; writing report without AI section.
+`
+    );
+    return report.markdown;
+  }
+}
+export {
+  enhanceMarkdownIfConfigured
+};

package/dist/esm/runner/batchRunner.js

@@ -0,0 +1,56 @@
+import { ScenarioRunner } from "./scenarioRunner.js";
+function buildSummary(results) {
+  return {
+    results,
+    totalDurationMs: results.reduce((acc, r) => acc + r.durationMs, 0),
+    passCount: results.filter((r) => r.passed).length,
+    failCount: results.filter((r) => !r.passed).length
+  };
+}
+class BatchRunner {
+  constructor(config, registry) {
+    this.config = config;
+    this.registry = registry;
+    this.scenarioRunner = new ScenarioRunner(config);
+  }
+  config;
+  registry;
+  scenarioRunner;
+  async runAll() {
+    const scenarios = this.registry.list().map((entry) => entry.scenario);
+    return this.executeScenarios(scenarios);
+  }
+  async runByTag(tag) {
+    const scenarios = this.registry.filterByTag(tag).map((entry) => entry.scenario);
+    return this.executeScenarios(scenarios);
+  }
+  async runByName(key) {
+    const scenario = this.registry.get(key);
+    if (!scenario) {
+      throw new Error(`No scenario registered with key "${key}"`);
+    }
+    return this.executeScenarios([scenario]);
+  }
+  async executeScenarios(scenarios) {
+    const results = await scenarios.reduce(
+      async (acc, scenario) => {
+        const prior = await acc;
+        const result = await this.runOne(scenario);
+        return [...prior, result];
+      },
+      Promise.resolve([])
+    );
+    return buildSummary(results);
+  }
+  async runOne(scenario) {
+    const browser = await this.scenarioRunner.launchBrowser();
+    try {
+      return await this.scenarioRunner.run(scenario, browser);
+    } finally {
+      await browser.close();
+    }
+  }
+}
+export {
+  BatchRunner
+};

package/dist/esm/runner/scenarioRunner.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  chromium
+} from "@playwright/test";
+import { AuthManager, PageSetup } from "@elliemae/smoked-suite";
+import { IframeHeapProfiler } from "../browser/iframeHeapProfiler.js";
+import { ThresholdEvaluator } from "../analysis/thresholdEvaluator.js";
+import { DEFAULT_THRESHOLDS } from "../types/config.js";
+import { enhanceMarkdownIfConfigured } from "./aiEnhancementStep.js";
+async function resolveIframe(page, selector) {
+  const handle = await page.locator(selector).elementHandle();
+  if (!handle) throw new Error(`Iframe not found for selector: ${selector}`);
+  const frame = await handle.contentFrame();
+  if (!frame)
+    throw new Error(`Could not get content frame for selector: ${selector}`);
+  return frame;
+}
+async function forceGarbageCollection(page) {
+  const session = await page.context().newCDPSession(page);
+  await session.send("HeapProfiler.enable");
+  await session.send("HeapProfiler.collectGarbage");
+  await session.send("HeapProfiler.disable");
+  await session.detach();
+  await page.waitForTimeout(2e3);
+}
+function cleanupSnapshots(paths) {
+  if (paths.before && fs.existsSync(paths.before)) fs.unlinkSync(paths.before);
+  if (paths.after && fs.existsSync(paths.after)) fs.unlinkSync(paths.after);
+}
+class ScenarioRunner {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async launchBrowser() {
+    return chromium.launch({ headless: this.config.runner.headless });
+  }
+  async run(scenario, browser) {
+    const startTime = Date.now();
+    const context = await browser.newContext({
+      baseURL: this.config.env.baseUrl
+    });
+    const page = await context.newPage();
+    const paths = { before: "", after: "" };
+    let report = null;
+    let error = null;
+    try {
+      report = await this.runScenarioInPage(page, scenario, paths);
+    } catch (err) {
+      error = err instanceof Error ? err : new Error(String(err));
+    } finally {
+      await context.close();
+      cleanupSnapshots(paths);
+    }
+    return this.buildResult({ scenario, report, error, startTime });
+  }
+  async runScenarioInPage(page, scenario, paths) {
+    const snapshotsDir = path.join(this.config.runner.outputDir, "snapshots");
+    const { profiler, frame } = await this.setupAndProfile(
+      page,
+      scenario,
+      snapshotsDir
+    );
+    paths.before = await profiler.captureSnapshot("before");
+    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
+    );
+    if (report) await this.writeReport(report, scenario);
+    return report;
+  }
+  async setupAndProfile(page, scenario, snapshotsDir) {
+    const auth = new AuthManager();
+    const pageSetup = new PageSetup();
+    await pageSetup.apply(page);
+    await auth.login(page, {
+      username: this.config.env.userId,
+      password: this.config.env.password,
+      instanceId: this.config.env.instanceId
+    });
+    await page.goto(scenario.url());
+    const frame = await resolveIframe(page, scenario.microappSelector);
+    fs.mkdirSync(snapshotsDir, { recursive: true });
+    const profiler = new IframeHeapProfiler(page, frame, snapshotsDir);
+    return { profiler, frame };
+  }
+  async repeatScenarioActions(scenario, page, frame) {
+    const repeatCount = scenario.repeat?.() ?? 3;
+    for (let i = 0; i < repeatCount; i += 1) {
+      await scenario.action(page, frame);
+      if (scenario.back) {
+        await scenario.back(page);
+      }
+    }
+  }
+  async writeReport(report, scenario) {
+    const reportPath = path.join(
+      this.config.runner.outputDir,
+      `${scenario.id}.md`
+    );
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+    const markdown = await enhanceMarkdownIfConfigured(
+      report,
+      this.config,
+      scenario.name
+    );
+    fs.writeFileSync(reportPath, markdown);
+  }
+  buildResult(input) {
+    const { scenario, report, error, startTime } = input;
+    const thresholds = {
+      ...DEFAULT_THRESHOLDS,
+      ...scenario.thresholds
+    };
+    const failureFallback = {
+      passed: false,
+      reason: error?.message ?? "Snapshot capture failed"
+    };
+    const thresholdResult = report && !error ? ThresholdEvaluator.evaluate(report, thresholds) : failureFallback;
+    return {
+      name: scenario.name,
+      passed: thresholdResult.passed,
+      thresholdResult,
+      report,
+      durationMs: Date.now() - startTime,
+      error
+    };
+  }
+}
+export {
+  ScenarioRunner
+};

package/dist/esm/scenarios/index.js

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

package/dist/esm/scenarios/one-admin/export-navigation.scenario.js

@@ -0,0 +1,33 @@
+import {
+  SelectSettingsPageModel,
+  ExportPageModel
+} from "./page-models/index.js";
+const exportNavigationScenario = {
+  id: "export-navigation",
+  name: "Export Navigation",
+  description: "Navigate to export page and come back - verify iframe GC",
+  tags: ["critical"],
+  microappSelector: "iframe#pui-iframe-container-emAdminUI",
+  url: () => "/admin/oneadmin/migrate",
+  async action(page, frame) {
+    const settings = new SelectSettingsPageModel(frame);
+    await settings.container.waitFor({ state: "visible" });
+    await settings.expandTreeItem("eFolder");
+    await settings.selectTreeItem("Enhanced Conditions");
+    await settings.clickExport();
+    const exportPage = new ExportPageModel(frame);
+    await exportPage.sourceDataTab.waitFor({ state: "visible" });
+    await exportPage.dataTable.waitFor({ state: "visible" });
+  },
+  async back(page) {
+    await ExportPageModel.clickBackAndWaitForSettings(page);
+  },
+  repeat: () => 3,
+  thresholds: {
+    maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
+    maxNewLeakGroups: 0
+  }
+};
+export {
+  exportNavigationScenario
+};

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

@@ -0,0 +1,7 @@
+import { exportNavigationScenario } from "./export-navigation.scenario.js";
+const oneAdminScenarios = [
+  exportNavigationScenario
+];
+export {
+  oneAdminScenarios
+};

package/dist/esm/scenarios/one-admin/page-models/ExportPageModel.js

@@ -0,0 +1,23 @@
+const IFRAME_SELECTOR = "iframe#pui-iframe-container-emAdminUI";
+const SETTINGS_URL_PATTERN = /\/admin\/oneadmin\/migrate(?:\/)?$/;
+class ExportPageModel {
+  constructor(frame) {
+    this.frame = frame;
+  }
+  frame;
+  get sourceDataTab() {
+    return this.frame.getByRole("tab", { name: /Source Data/i });
+  }
+  get dataTable() {
+    return this.frame.locator('[role="table"]').first();
+  }
+  static async clickBackAndWaitForSettings(page) {
+    await Promise.all([
+      page.waitForURL(SETTINGS_URL_PATTERN),
+      page.frameLocator(IFRAME_SELECTOR).getByRole("button", { name: /back/i }).click()
+    ]);
+  }
+}
+export {
+  ExportPageModel
+};

package/dist/esm/scenarios/one-admin/page-models/SelectSettingsPageModel.js

@@ -0,0 +1,27 @@
+class SelectSettingsPageModel {
+  constructor(frame) {
+    this.frame = frame;
+  }
+  frame;
+  get container() {
+    return this.frame.locator("#one-admin-console-container");
+  }
+  get exportButton() {
+    return this.frame.getByRole("button", { name: "Export" });
+  }
+  async expandTreeItem(name) {
+    const treeItem = this.frame.locator(
+      `[role="treeitem"]:has-text("${name}")`
+    );
+    await treeItem.locator('button[aria-label*="expand"], button[aria-label*="toggle"]').click();
+  }
+  async selectTreeItem(name) {
+    await this.frame.locator(`[role="treeitem"]:has-text("${name}")`).click();
+  }
+  async clickExport() {
+    await this.exportButton.click();
+  }
+}
+export {
+  SelectSettingsPageModel
+};

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

@@ -0,0 +1,6 @@
+import { SelectSettingsPageModel } from "./SelectSettingsPageModel.js";
+import { ExportPageModel } from "./ExportPageModel.js";
+export {
+  ExportPageModel,
+  SelectSettingsPageModel
+};

package/dist/esm/types/config.js

@@ -0,0 +1,7 @@
+const DEFAULT_THRESHOLDS = {
+  maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
+  maxNewLeakGroups: 0
+};
+export {
+  DEFAULT_THRESHOLDS
+};

package/dist/types/bin/leak-runner.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/lib/analysis/tests/thresholdEvaluator.test.d.ts

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

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

@@ -0,0 +1,6 @@
+import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
+import type { ResolvedThresholds } from '../types/config.js';
+import type { ThresholdResult } from '../types/results.js';
+export declare class ThresholdEvaluator {
+    static evaluate(report: ComparisonReport, thresholds: ResolvedThresholds): ThresholdResult;
+}

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

@@ -0,0 +1,9 @@
+import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
+import type { Page, Frame } from '@playwright/test';
+export declare class IframeHeapProfiler extends HeapMemoryProfiler {
+    private readonly profiledPage;
+    private readonly frame;
+    constructor(profiledPage: Page, frame: Frame, outputDir: string);
+    protected getCDPTarget(): Page | Frame;
+    private isSameOriginAsPage;
+}

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

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

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

@@ -0,0 +1,17 @@
+import type { Command } from 'commander';
+import type { ScenarioRegistry } from '../registry/scenarioRegistry.js';
+import type { RequiredEnvParamsResolver } from '../config/requiredEnvParams.js';
+/**
+ * Dependencies a CliCommand needs from the surrounding wiring.
+ *
+ * `RunnerConfigLoader` is intentionally NOT here — each command invocation
+ * builds its own loader so it can layer in command-line flags (which are only
+ * known per-invocation).
+ */
+export interface CliDependencies {
+    readonly registry: ScenarioRegistry;
+    readonly envParams: RequiredEnvParamsResolver;
+}
+export interface CliCommand {
+    register(program: Command, deps: CliDependencies): void;
+}

package/dist/types/lib/cli/commands/listCommand.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+import type { CliCommand, CliDependencies } from '../command.js';
+export declare class ListCommand implements CliCommand {
+    register(program: Command, deps: CliDependencies): void;
+}

package/dist/types/lib/cli/commands/runCommand.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import type { CliCommand, CliDependencies } from '../command.js';
+export declare class RunCommand implements CliCommand {
+    register(program: Command, deps: CliDependencies): void;
+    private buildConfig;
+    private selectSummary;
+}

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

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+import type { CliDependencies } from './command.js';
+export declare function buildProgram(deps?: CliDependencies): Command;
+export declare function defaultDeps(): CliDependencies;

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

@@ -0,0 +1,4 @@
+export declare class MissingRequiredParamError extends Error {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}

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

@@ -0,0 +1,16 @@
+import type { EnvironmentParams } from '../types/config.js';
+import { MissingRequiredParamError } from './missingRequiredParamError.js';
+export interface CliEnvOpts {
+    readonly baseUrl?: string;
+    readonly instanceId?: string;
+    readonly userId?: string;
+}
+export { MissingRequiredParamError };
+export declare class RequiredEnvParamsResolver {
+    resolve(cliOpts: CliEnvOpts): EnvironmentParams;
+    private resolveBaseUrl;
+    private resolveInstanceId;
+    private resolveUserId;
+    private resolvePassword;
+    private collectMissing;
+}

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

@@ -0,0 +1,13 @@
+import type { RunnerOptions } from '../types/config.js';
+import type { ConfigSource } from './sources/configSource.js';
+export interface ResolvedRunnerConfigPartial {
+    readonly runner: RunnerOptions;
+    readonly aiEnabled: boolean;
+    readonly aiModel: string;
+    readonly aiTemperature: number;
+}
+export declare class RunnerConfigLoader {
+    private readonly sources;
+    constructor(sources: readonly ConfigSource[]);
+    resolveOptions(): ResolvedRunnerConfigPartial;
+}