@elliemae/encw-leak-runner 1.0.2

package/lib/config/tests/fileConfigSource.test.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { FileConfigSource } from '../sources/fileConfigSource.js';
+
+function makeTempFile(content: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'leak-runner-cfg-'));
+  const file = path.join(dir, 'leak-runner.config.json');
+  fs.writeFileSync(file, content);
+  return file;
+}
+
+describe('FileConfigSource', () => {
+  it('returns an empty payload when the file does not exist', () => {
+    const src = new FileConfigSource('/path/that/does/not/exist.json');
+    expect(src.load()).toEqual({});
+  });
+
+  it('parses and validates a well-formed config file', () => {
+    const file = makeTempFile(
+      JSON.stringify({
+        runner: { headless: false, outputDir: './out/', topN: 3 },
+        ai: { enabled: true, model: 'Claude3.7', temperature: 0.2 },
+      }),
+    );
+    const src = new FileConfigSource(file);
+    expect(src.load()).toEqual({
+      runner: { headless: false, outputDir: './out/', topN: 3 },
+      ai: { enabled: true, model: 'Claude3.7', temperature: 0.2 },
+    });
+  });
+
+  it('throws a descriptive error when the JSON is invalid', () => {
+    const file = makeTempFile('{not-valid-json');
+    const src = new FileConfigSource(file);
+    expect(() => src.load()).toThrow(/Failed to parse config file/);
+  });
+
+  it('throws a descriptive error when the schema is violated', () => {
+    const file = makeTempFile(JSON.stringify({ runner: { topN: 'banana' } }));
+    const src = new FileConfigSource(file);
+    expect(() => src.load()).toThrow(/Invalid config file/);
+  });
+
+  it('exposes priority 1 (lowest tier above defaults)', () => {
+    const src = new FileConfigSource('/anything');
+    expect(src.priority).toBe(1);
+  });
+});

package/lib/config/tests/requiredEnvParams.test.ts

@@ -0,0 +1,113 @@
+import { RequiredEnvParamsResolver } from '../requiredEnvParams.js';
+import { MissingRequiredParamError } from '../missingRequiredParamError.js';
+
+describe('RequiredEnvParamsResolver', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.BASE_URL;
+    delete process.env.ENCW_INSTANCE_ID;
+    delete process.env.ENCW_USER_ID;
+    delete process.env.ENCW_PASSWORD;
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('throws MissingRequiredParamError listing every missing field when nothing is provided', () => {
+    const resolver = new RequiredEnvParamsResolver();
+    let caught: unknown;
+    try {
+      resolver.resolve({});
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(MissingRequiredParamError);
+    const err = caught as MissingRequiredParamError;
+    expect(err.missing).toEqual([
+      'baseUrl',
+      'instanceId',
+      'userId',
+      'password (ENCW_PASSWORD)',
+    ]);
+    expect(err.message).toContain('--base-url');
+    expect(err.message).toContain('ENCW_PASSWORD');
+  });
+
+  it('reads from env vars when CLI options are absent', () => {
+    process.env.BASE_URL = 'https://q3.elliemae.io';
+    process.env.ENCW_INSTANCE_ID = 'BE1';
+    process.env.ENCW_USER_ID = 'admin';
+    process.env.ENCW_PASSWORD = 'pw';
+
+    const resolver = new RequiredEnvParamsResolver();
+    expect(resolver.resolve({})).toEqual({
+      baseUrl: 'https://q3.elliemae.io',
+      instanceId: 'BE1',
+      userId: 'admin',
+      password: 'pw',
+    });
+  });
+
+  it('CLI options override env vars for non-secret fields', () => {
+    process.env.BASE_URL = 'https://q3.elliemae.io';
+    process.env.ENCW_INSTANCE_ID = 'BE1';
+    process.env.ENCW_USER_ID = 'admin';
+    process.env.ENCW_PASSWORD = 'pw';
+
+    const resolver = new RequiredEnvParamsResolver();
+    expect(
+      resolver.resolve({
+        baseUrl: 'https://q4.elliemae.io',
+        instanceId: 'BE2',
+        userId: 'user2',
+      }),
+    ).toEqual({
+      baseUrl: 'https://q4.elliemae.io',
+      instanceId: 'BE2',
+      userId: 'user2',
+      password: 'pw',
+    });
+  });
+
+  it('password is read only from process.env (no CLI flag for secrets)', () => {
+    process.env.BASE_URL = 'https://q3.elliemae.io';
+    process.env.ENCW_INSTANCE_ID = 'BE1';
+    process.env.ENCW_USER_ID = 'admin';
+    // ENCW_PASSWORD intentionally unset
+
+    const resolver = new RequiredEnvParamsResolver();
+    expect(() => resolver.resolve({})).toThrow(MissingRequiredParamError);
+  });
+
+  it('reports only the missing fields when some are supplied', () => {
+    process.env.BASE_URL = 'https://q3.elliemae.io';
+    // ENCW_INSTANCE_ID, ENCW_USER_ID, ENCW_PASSWORD missing
+
+    const resolver = new RequiredEnvParamsResolver();
+    let caught: unknown;
+    try {
+      resolver.resolve({});
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as MissingRequiredParamError;
+    expect(err.missing).toEqual([
+      'instanceId',
+      'userId',
+      'password (ENCW_PASSWORD)',
+    ]);
+  });
+
+  it('treats empty-string env vars as missing', () => {
+    process.env.BASE_URL = '';
+    process.env.ENCW_INSTANCE_ID = '';
+    process.env.ENCW_USER_ID = '';
+    process.env.ENCW_PASSWORD = '';
+
+    const resolver = new RequiredEnvParamsResolver();
+    expect(() => resolver.resolve({})).toThrow(/Missing required parameter/);
+  });
+});

package/lib/config/tests/runnerConfigLoader.test.ts

@@ -0,0 +1,59 @@
+import { RunnerConfigLoader } from '../runnerConfigLoader.js';
+import type { ConfigSource } from '../sources/configSource.js';
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+
+function fakeSource(
+  priority: number,
+  name: string,
+  payload: Partial<RawRunnerConfigFile>,
+): ConfigSource {
+  return { priority, name, load: () => payload };
+}
+
+describe('RunnerConfigLoader', () => {
+  it('produces built-in defaults when no source contributes', () => {
+    const loader = new RunnerConfigLoader([]);
+    const resolved = loader.resolveOptions();
+    expect(resolved.runner).toEqual({
+      headless: true,
+      outputDir: './leak-reports/',
+      topN: 5,
+    });
+    expect(resolved.aiEnabled).toBe(false);
+  });
+
+  it('higher-priority sources override lower-priority sources', () => {
+    const file = fakeSource(1, 'file', { runner: { topN: 1, headless: true } });
+    const env = fakeSource(2, 'env', { runner: { topN: 2 } });
+    const cli = fakeSource(3, 'cli', { runner: { topN: 9 } });
+    const loader = new RunnerConfigLoader([file, env, cli]);
+    expect(loader.resolveOptions().runner.topN).toBe(9);
+  });
+
+  it('merges shallow keys without dropping unrelated fields', () => {
+    const file = fakeSource(1, 'file', {
+      runner: { headless: false, outputDir: './out/' },
+    });
+    const cli = fakeSource(3, 'cli', { runner: { topN: 8 } });
+    const loader = new RunnerConfigLoader([file, cli]);
+    expect(loader.resolveOptions().runner).toEqual({
+      headless: false,
+      outputDir: './out/',
+      topN: 8,
+    });
+  });
+
+  it('exposes ai defaults and reports aiEnabled=false when not set', () => {
+    const loader = new RunnerConfigLoader([]);
+    const resolved = loader.resolveOptions();
+    expect(resolved.aiEnabled).toBe(false);
+    expect(resolved.aiModel).toBe('Claude3.7');
+    expect(resolved.aiTemperature).toBe(0.3);
+  });
+
+  it('reports aiEnabled=true when a source enables it', () => {
+    const file = fakeSource(1, 'file', { ai: { enabled: true } });
+    const loader = new RunnerConfigLoader([file]);
+    expect(loader.resolveOptions().aiEnabled).toBe(true);
+  });
+});

package/lib/index.ts

@@ -0,0 +1,37 @@
+// === Tier 1 — Scenario authoring (the most-used surface) ===
+export type { MicroappLeakScenario } from './types/scenario.js';
+export type {
+  EnvironmentParams,
+  RunnerOptions,
+  AiConfig,
+  RunnerConfig,
+  ResolvedThresholds,
+} from './types/config.js';
+export { DEFAULT_THRESHOLDS } from './types/config.js';
+export type {
+  ScenarioGroup,
+  ScenarioEntry,
+} from './registry/scenarioRegistry.js';
+export type {
+  ThresholdResult,
+  ScenarioResult,
+  RunSummary,
+} from './types/results.js';
+
+// === Tier 2 — Embedding (UNSTABLE — no backwards-compat guarantee yet) ===
+export { ScenarioRegistry } from './registry/scenarioRegistry.js';
+export { BatchRunner } from './runner/batchRunner.js';
+export { ScenarioRunner } from './runner/scenarioRunner.js';
+export { IframeHeapProfiler } from './browser/iframeHeapProfiler.js';
+export { ThresholdEvaluator } from './analysis/thresholdEvaluator.js';
+export { ConsoleReporter } from './reporting/consoleReporter.js';
+export { JunitReporter } from './reporting/junitReporter.js';
+export { RunnerConfigLoader } from './config/runnerConfigLoader.js';
+export { FileConfigSource } from './config/sources/fileConfigSource.js';
+export { EnvVarConfigSource } from './config/sources/envVarConfigSource.js';
+export { CliOverrideConfigSource } from './config/sources/cliOverrideConfigSource.js';
+export {
+  RequiredEnvParamsResolver,
+  MissingRequiredParamError,
+} from './config/requiredEnvParams.js';
+export { buildProgram, defaultDeps } from './cli/index.js';

package/lib/registry/scenarioRegistry.ts

@@ -0,0 +1,48 @@
+import type { MicroappLeakScenario } from '../types/scenario.js';
+
+export interface ScenarioGroup {
+  readonly microapp: string;
+  readonly scenarios: readonly MicroappLeakScenario[];
+}
+
+export interface ScenarioEntry {
+  readonly key: string;
+  readonly scenario: MicroappLeakScenario;
+}
+
+export class ScenarioRegistry {
+  private readonly entries = new Map<string, MicroappLeakScenario>();
+
+  register(group: ScenarioGroup): this {
+    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: string): MicroappLeakScenario | undefined {
+    return this.entries.get(key);
+  }
+
+  has(key: string): boolean {
+    return this.entries.has(key);
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  list(): readonly ScenarioEntry[] {
+    return Array.from(this.entries.entries())
+      .map(([key, scenario]) => ({ key, scenario }))
+      .sort((a, b) => a.key.localeCompare(b.key));
+  }
+
+  filterByTag(tag: string): readonly ScenarioEntry[] {
+    return this.list().filter((entry) => entry.scenario.tags?.includes(tag));
+  }
+}

package/lib/registry/tests/scenarioRegistry.test.ts

@@ -0,0 +1,96 @@
+import type { MicroappLeakScenario } from '../../types/scenario.js';
+import { ScenarioRegistry } from '../scenarioRegistry.js';
+
+function makeScenario(
+  id: string,
+  overrides: Partial<MicroappLeakScenario> = {},
+): MicroappLeakScenario {
+  return {
+    id,
+    name: id.replace(/-/g, ' '),
+    description: `${id} description`,
+    microappSelector: `iframe#${id}`,
+    url: () => `/${id}`,
+    action: () => Promise.resolve(),
+    ...overrides,
+  };
+}
+
+describe('ScenarioRegistry', () => {
+  it('starts empty', () => {
+    expect(new ScenarioRegistry().size()).toBe(0);
+  });
+
+  it('builds keys as <microapp>/<scenario.id> when registering a group', () => {
+    const reg = new ScenarioRegistry().register({
+      microapp: 'one-admin',
+      scenarios: [makeScenario('export-navigation')],
+    });
+    expect(reg.size()).toBe(1);
+    expect(reg.has('one-admin/export-navigation')).toBe(true);
+  });
+
+  it('register() returns `this` to support chaining', () => {
+    const reg = new ScenarioRegistry();
+    const out = reg.register({ microapp: 'one-admin', scenarios: [] });
+    expect(out).toBe(reg);
+  });
+
+  it('throws when registering a duplicate key', () => {
+    const reg = new ScenarioRegistry().register({
+      microapp: 'one-admin',
+      scenarios: [makeScenario('export-navigation')],
+    });
+    expect(() =>
+      reg.register({
+        microapp: 'one-admin',
+        scenarios: [makeScenario('export-navigation')],
+      }),
+    ).toThrow('Duplicate scenario: one-admin/export-navigation');
+  });
+
+  it('get() returns the registered scenario', () => {
+    const scenario = makeScenario('export-navigation');
+    const reg = new ScenarioRegistry().register({
+      microapp: 'one-admin',
+      scenarios: [scenario],
+    });
+    expect(reg.get('one-admin/export-navigation')).toBe(scenario);
+  });
+
+  it('get() returns undefined for an unknown key', () => {
+    const reg = new ScenarioRegistry();
+    expect(reg.get('unknown/scenario')).toBeUndefined();
+  });
+
+  it('list() returns entries sorted by key', () => {
+    const reg = new ScenarioRegistry()
+      .register({ microapp: 'beta', scenarios: [makeScenario('two')] })
+      .register({ microapp: 'alpha', scenarios: [makeScenario('one')] });
+
+    const keys = reg.list().map((entry) => entry.key);
+    expect(keys).toEqual(['alpha/one', 'beta/two']);
+  });
+
+  it('filterByTag() returns only scenarios that include the tag', () => {
+    const reg = new ScenarioRegistry().register({
+      microapp: 'one-admin',
+      scenarios: [
+        makeScenario('a', { tags: ['critical'] }),
+        makeScenario('b', { tags: ['optional'] }),
+        makeScenario('c', { tags: ['critical', 'smoke'] }),
+      ],
+    });
+
+    const keys = reg.filterByTag('critical').map((entry) => entry.key);
+    expect(keys).toEqual(['one-admin/a', 'one-admin/c']);
+  });
+
+  it('filterByTag() returns an empty array when no scenarios match', () => {
+    const reg = new ScenarioRegistry().register({
+      microapp: 'one-admin',
+      scenarios: [makeScenario('a', { tags: ['critical'] })],
+    });
+    expect(reg.filterByTag('missing')).toEqual([]);
+  });
+});

package/lib/reporting/consoleReporter.ts

@@ -0,0 +1,48 @@
+import type { Reporter } from './reporter.js';
+import type { RunSummary, ScenarioResult } from '../types/results.js';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function formatDuration(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function printLine(text: string): void {
+  process.stdout.write(`${text}\n`);
+}
+
+function printScenario(result: ScenarioResult): void {
+  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}→ ${result.thresholdResult.reason}${RESET}`);
+  }
+  if (!result.passed && result.error) {
+    printLine(`         ${RED}→ Error: ${result.error.message}${RESET}`);
+  }
+}
+
+export class ConsoleReporter implements Reporter {
+  write(summary: RunSummary): void {
+    printLine('');
+    printLine(`${BOLD}MEMORY LEAK RUN RESULTS${RESET}`);
+    printLine('─'.repeat(50));
+
+    summary.results.forEach(printScenario);
+
+    printLine('─'.repeat(50));
+    const total = summary.results.length;
+    const duration = formatDuration(summary.totalDurationMs);
+    printLine(
+      `${summary.passCount} passed, ${summary.failCount} failed ` +
+        `of ${total} scenarios  (${duration})`,
+    );
+    printLine('');
+  }
+}

package/lib/reporting/junitReporter.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Reporter } from './reporter.js';
+import type { RunSummary, ScenarioResult } from '../types/results.js';
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function formatSeconds(ms: number): string {
+  return (ms / 1000).toFixed(1);
+}
+
+function renderTestCase(result: ScenarioResult): string {
+  const timeAttr = `time="${formatSeconds(result.durationMs)}"`;
+  const open = `    <testcase name="${escapeXml(
+    result.name,
+  )}" classname="memory-leak" ${timeAttr}>`;
+
+  if (result.passed) {
+    return `${open}\n    </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}\n` +
+    `      <failure message="${escapeXml(message)}">\n` +
+    `        ${escapeXml(body)}\n` +
+    `      </failure>\n` +
+    `    </testcase>`
+  );
+}
+
+export class JunitReporter implements Reporter {
+  write(summary: RunSummary, outputDir: string): Promise<void> {
+    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();
+  }
+}

package/lib/reporting/reporter.ts

@@ -0,0 +1,5 @@
+import type { RunSummary } from '../types/results.js';
+
+export interface Reporter {
+  write(summary: RunSummary, outputDir: string): void | Promise<void>;
+}

package/lib/reporting/tests/consoleReporter.test.ts

@@ -0,0 +1,82 @@
+import { ConsoleReporter } from '../consoleReporter.js';
+import type { RunSummary } from '../../types/results.js';
+
+function makeSummary(overrides: Partial<RunSummary> = {}): RunSummary {
+  return {
+    results: [],
+    totalDurationMs: 5000,
+    passCount: 0,
+    failCount: 0,
+    ...overrides,
+  };
+}
+
+describe('ConsoleReporter', () => {
+  let reporter: ConsoleReporter;
+  type StdSpy = jest.SpyInstance<boolean, [string | Uint8Array, ...unknown[]]>;
+  let stdoutSpy: StdSpy;
+
+  beforeEach(() => {
+    reporter = new ConsoleReporter();
+    stdoutSpy = jest
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true) as StdSpy;
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+  });
+
+  it('prints PASSED for a passing scenario', () => {
+    const summary = makeSummary({
+      passCount: 1,
+      results: [
+        {
+          name: 'loan-pipeline',
+          passed: true,
+          thresholdResult: { passed: true, reason: null },
+          report: null,
+          durationMs: 2000,
+          error: null,
+        },
+      ],
+    });
+
+    reporter.write(summary);
+    const output = stdoutSpy.mock.calls.map((c) => String(c[0])).join('');
+    expect(output).toContain('loan-pipeline');
+    expect(output).toContain('PASSED');
+  });
+
+  it('prints FAILED with reason for a failing scenario', () => {
+    const summary = makeSummary({
+      failCount: 1,
+      results: [
+        {
+          name: 'document-center',
+          passed: false,
+          thresholdResult: {
+            passed: false,
+            reason: 'Retained size delta 18.4 MB exceeds threshold 10.0 MB',
+          },
+          report: null,
+          durationMs: 3000,
+          error: null,
+        },
+      ],
+    });
+
+    reporter.write(summary);
+    const output = stdoutSpy.mock.calls.map((c) => String(c[0])).join('');
+    expect(output).toContain('document-center');
+    expect(output).toContain('FAILED');
+    expect(output).toContain('18.4 MB');
+  });
+
+  it('prints overall summary line with pass and fail counts', () => {
+    const summary = makeSummary({ passCount: 2, failCount: 1 });
+    reporter.write(summary);
+    const output = stdoutSpy.mock.calls.map((c) => String(c[0])).join('');
+    expect(output).toMatch(/2 passed.*1 failed/i);
+  });
+});