@elliemae/encw-leak-runner 1.0.2

package/lib/browser/tests/iframeHeapProfiler.test.ts

@@ -0,0 +1,71 @@
+import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
+import type { Page, Frame } from '@playwright/test';
+import { IframeHeapProfiler } from '../iframeHeapProfiler.js';
+
+// `getCDPTarget` is protected on the real classes; tests need structural access.
+type ProfilerInternals = { getCDPTarget(): Page | Frame };
+
+function exposeInternals(profiler: HeapMemoryProfiler): ProfilerInternals {
+  return profiler as unknown as ProfilerInternals;
+}
+
+function makeMockPage(
+  url = 'https://q3.elliemae.io/admin',
+  browserName = 'chromium',
+): Page {
+  return {
+    url: () => url,
+    context: () => ({
+      browser: () => ({ browserType: () => ({ name: () => browserName }) }),
+      newCDPSession: jest.fn().mockResolvedValue({
+        send: jest.fn().mockResolvedValue(undefined),
+        on: jest.fn(),
+        detach: jest.fn().mockResolvedValue(undefined),
+      }),
+    }),
+  } as unknown as Page;
+}
+
+function makeMockFrame(url = 'https://q3.elliemae.io'): Frame {
+  return { url: () => url } as unknown as Frame;
+}
+
+describe('IframeHeapProfiler', () => {
+  it('is an instance of HeapMemoryProfiler', () => {
+    const page = makeMockPage();
+    const frame = makeMockFrame();
+    const profiler = new IframeHeapProfiler(page, frame, '/tmp/test');
+    expect(profiler).toBeInstanceOf(HeapMemoryProfiler);
+  });
+
+  it('returns the page as CDP target when the iframe is same-origin', () => {
+    const page = makeMockPage('https://q3.elliemae.io/admin');
+    const frame = makeMockFrame('https://q3.elliemae.io/admin/microapp');
+    const profiler = new IframeHeapProfiler(page, frame, '/tmp/test');
+    const target = exposeInternals(profiler).getCDPTarget();
+    expect(target).toBe(page);
+  });
+
+  it('returns the frame as CDP target when the iframe is cross-origin (OOPIF)', () => {
+    const page = makeMockPage('https://q3.elliemae.io/admin');
+    const frame = makeMockFrame('https://other.example.com/microapp');
+    const profiler = new IframeHeapProfiler(page, frame, '/tmp/test');
+    const target = exposeInternals(profiler).getCDPTarget();
+    expect(target).toBe(frame);
+  });
+
+  it('treats an about:blank frame as same-origin and returns the page', () => {
+    const page = makeMockPage('https://q3.elliemae.io/admin');
+    const frame = makeMockFrame('about:blank');
+    const profiler = new IframeHeapProfiler(page, frame, '/tmp/test');
+    const target = exposeInternals(profiler).getCDPTarget();
+    expect(target).toBe(page);
+  });
+
+  it('base HeapMemoryProfiler returns page as CDP target', () => {
+    const page = makeMockPage();
+    const profiler = new HeapMemoryProfiler(page, '/tmp/test');
+    const target = exposeInternals(profiler).getCDPTarget();
+    expect(target).toBe(page);
+  });
+});

package/lib/cli/command.ts

@@ -0,0 +1,19 @@
+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/lib/cli/commands/listCommand.ts

@@ -0,0 +1,36 @@
+import type { Command } from 'commander';
+import type { CliCommand, CliDependencies } from '../command.js';
+
+export class ListCommand implements CliCommand {
+  register(program: Command, deps: CliDependencies): void {
+    program
+      .command('list')
+      .description('List all registered scenarios')
+      .option('--tag <tag>', 'Filter by tag')
+      .action((options: { tag?: string }) => {
+        const entries = options.tag
+          ? deps.registry.filterByTag(options.tag)
+          : deps.registry.list();
+
+        if (entries.length === 0) {
+          process.stdout.write('No scenarios found.\n');
+          return;
+        }
+
+        const keyWidth = Math.max(...entries.map((e) => e.key.length), 32);
+        process.stdout.write(`\nREGISTERED SCENARIOS (${entries.length})\n\n`);
+
+        entries.forEach(({ key, scenario }) => {
+          const tags = scenario.tags?.length
+            ? `[${scenario.tags.join(', ')}]`
+            : '';
+          process.stdout.write(
+            `  ${key.padEnd(keyWidth)}  ${tags.padEnd(20)}  ${
+              scenario.description
+            }\n`,
+          );
+        });
+        process.stdout.write('\n');
+      });
+  }
+}

package/lib/cli/commands/runCommand.ts

@@ -0,0 +1,126 @@
+import type { Command } from 'commander';
+import type { CliCommand, CliDependencies } from '../command.js';
+import type { RunSummary } from '../../types/results.js';
+import type { RunnerConfig, AiConfig } from '../../types/config.js';
+import { BatchRunner } from '../../runner/batchRunner.js';
+import { ConsoleReporter } from '../../reporting/consoleReporter.js';
+import { JunitReporter } from '../../reporting/junitReporter.js';
+import {
+  CliOverrideConfigSource,
+  type CliRunnerOverrides,
+} from '../../config/sources/cliOverrideConfigSource.js';
+import { EnvVarConfigSource } from '../../config/sources/envVarConfigSource.js';
+import { FileConfigSource } from '../../config/sources/fileConfigSource.js';
+import { RunnerConfigLoader } from '../../config/runnerConfigLoader.js';
+import { MissingRequiredParamError } from '../../config/requiredEnvParams.js';
+
+interface RunOptions extends CliRunnerOverrides {
+  all?: boolean;
+  tag?: string;
+  baseUrl?: string;
+  instanceId?: string;
+  userId?: string;
+  configFile?: string;
+}
+
+export class RunCommand implements CliCommand {
+  register(program: Command, deps: CliDependencies): void {
+    program
+      .command('run [key]')
+      .description(
+        'Run a scenario by `<microapp>/<id>`, or use --all / --tag to run multiple',
+      )
+      .option('--all', 'Run all registered scenarios')
+      .option('--tag <tag>', 'Run all scenarios matching a tag')
+      .option('--base-url <url>', 'Override base URL')
+      .option('--instance-id <id>', 'Override instance ID')
+      .option('--user-id <id>', 'Override user ID')
+      .option('--output-dir <dir>', 'Override output directory')
+      .option('--top-n <n>', 'Override top-N for heap comparison', (v) =>
+        parseInt(v, 10),
+      )
+      .option(
+        '--headless <bool>',
+        'Override headless mode',
+        (v) => v !== 'false',
+      )
+      .option('--config-file <path>', 'Path to leak-runner.config.json')
+      .action(async (key: string | undefined, options: RunOptions) => {
+        try {
+          const config = this.buildConfig(options, deps);
+          const runner = new BatchRunner(config, deps.registry);
+          const summary = await this.selectSummary(runner, key, options);
+          new ConsoleReporter().write(summary);
+          await new JunitReporter().write(summary, config.runner.outputDir);
+          process.exit(summary.failCount > 0 ? 1 : 0);
+        } catch (err) {
+          if (err instanceof MissingRequiredParamError) {
+            process.stderr.write(`Configuration error: ${err.message}\n`);
+            process.exit(2);
+          }
+          process.stderr.write(`Fatal: ${(err as Error).message}\n`);
+          process.exit(1);
+        }
+      });
+  }
+
+  private buildConfig(
+    options: RunOptions,
+    deps: CliDependencies,
+  ): RunnerConfig {
+    const filePath =
+      options.configFile ?? `${process.cwd()}/leak-runner.config.json`;
+
+    const loader = new RunnerConfigLoader([
+      new FileConfigSource(filePath),
+      new EnvVarConfigSource(),
+      new CliOverrideConfigSource({
+        headless: options.headless,
+        outputDir: options.outputDir,
+        topN: options.topN,
+      }),
+    ]);
+    const resolved = loader.resolveOptions();
+
+    const env = deps.envParams.resolve({
+      baseUrl: options.baseUrl,
+      instanceId: options.instanceId,
+      userId: options.userId,
+    });
+
+    let ai: AiConfig | undefined;
+    if (resolved.aiEnabled) {
+      ai = {
+        model: resolved.aiModel,
+        temperature: resolved.aiTemperature,
+        apiKey: process.env.GENICE_API_KEY ?? '',
+      };
+    }
+
+    return { env, runner: resolved.runner, ai };
+  }
+
+  private async selectSummary(
+    runner: BatchRunner,
+    key: string | undefined,
+    options: RunOptions,
+  ): Promise<RunSummary> {
+    if (options.all) return runner.runAll();
+    if (options.tag) {
+      const summary = await runner.runByTag(options.tag);
+      if (summary.results.length === 0) {
+        process.stderr.write(
+          `Warning: no scenarios matched tag "${options.tag}"\n`,
+        );
+        process.exit(1);
+      }
+      return summary;
+    }
+    if (key) return runner.runByName(key);
+    process.stderr.write(
+      'Error: specify a scenario key (e.g. one-admin/export-navigation), --all, or --tag <tag>\n',
+    );
+    process.exit(1);
+    throw new Error('unreachable');
+  }
+}

package/lib/cli/index.ts

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+import type { CliCommand, CliDependencies } from './command.js';
+import { RunCommand } from './commands/runCommand.js';
+import { ListCommand } from './commands/listCommand.js';
+import { RequiredEnvParamsResolver } from '../config/requiredEnvParams.js';
+import { scenarioRegistry as populatedRegistry } from '../scenarios/index.js';
+
+export function buildProgram(deps: CliDependencies = defaultDeps()): Command {
+  const program = new Command();
+  program
+    .name('leak-runner')
+    .description('Microapp memory leak runner for Encompass Web')
+    .version('1.0.0');
+
+  const commands: readonly CliCommand[] = [new RunCommand(), new ListCommand()];
+  commands.forEach((cmd) => cmd.register(program, deps));
+  return program;
+}
+
+export function defaultDeps(): CliDependencies {
+  return {
+    registry: populatedRegistry,
+    envParams: new RequiredEnvParamsResolver(),
+  };
+}

package/lib/config/missingRequiredParamError.ts

@@ -0,0 +1,10 @@
+export class MissingRequiredParamError extends Error {
+  constructor(public readonly missing: readonly string[]) {
+    super(
+      `Missing required parameter(s): ${missing.join(', ')}.\n` +
+        `Provide via CLI flag (--base-url / --instance-id / --user-id) ` +
+        `or env var (BASE_URL / ENCW_INSTANCE_ID / ENCW_USER_ID / ENCW_PASSWORD).`,
+    );
+    this.name = 'MissingRequiredParamError';
+  }
+}

package/lib/config/requiredEnvParams.ts

@@ -0,0 +1,50 @@
+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 class RequiredEnvParamsResolver {
+  resolve(cliOpts: CliEnvOpts): EnvironmentParams {
+    const baseUrl = this.resolveBaseUrl(cliOpts);
+    const instanceId = this.resolveInstanceId(cliOpts);
+    const userId = this.resolveUserId(cliOpts);
+    const password = this.resolvePassword();
+
+    const params = { baseUrl, instanceId, userId, password };
+    const missing = this.collectMissing(params);
+    if (missing.length > 0) throw new MissingRequiredParamError(missing);
+
+    return params;
+  }
+
+  private resolveBaseUrl(cliOpts: CliEnvOpts): string {
+    return cliOpts.baseUrl || process.env.BASE_URL || '';
+  }
+
+  private resolveInstanceId(cliOpts: CliEnvOpts): string {
+    return cliOpts.instanceId || process.env.ENCW_INSTANCE_ID || '';
+  }
+
+  private resolveUserId(cliOpts: CliEnvOpts): string {
+    return cliOpts.userId || process.env.ENCW_USER_ID || '';
+  }
+
+  private resolvePassword(): string {
+    return process.env.ENCW_PASSWORD || '';
+  }
+
+  private collectMissing(params: EnvironmentParams): string[] {
+    const missing: string[] = [];
+    if (!params.baseUrl) missing.push('baseUrl');
+    if (!params.instanceId) missing.push('instanceId');
+    if (!params.userId) missing.push('userId');
+    if (!params.password) missing.push('password (ENCW_PASSWORD)');
+    return missing;
+  }
+}

package/lib/config/runnerConfigLoader.ts

@@ -0,0 +1,84 @@
+import type { RunnerOptions } from '../types/config.js';
+import type { RawRunnerConfigFile } from './runnerConfigSchema.js';
+import type { ConfigSource } from './sources/configSource.js';
+import { BUILT_IN_DEFAULTS } from './sources/configSource.js';
+
+export interface ResolvedRunnerConfigPartial {
+  readonly runner: RunnerOptions;
+  readonly aiEnabled: boolean;
+  readonly aiModel: string;
+  readonly aiTemperature: number;
+}
+
+type MutableRunner = { headless: boolean; outputDir: string; topN: number };
+
+type AiAccumulator = {
+  aiEnabled: boolean;
+  aiModel: string;
+  aiTemperature: number;
+};
+
+function applyRunnerPayload(
+  acc: MutableRunner,
+  payload: NonNullable<RawRunnerConfigFile['runner']>,
+): MutableRunner {
+  return {
+    headless: payload.headless ?? acc.headless,
+    outputDir: payload.outputDir ?? acc.outputDir,
+    topN: payload.topN ?? acc.topN,
+  };
+}
+
+function applyAiPayload(
+  acc: AiAccumulator,
+  payload: NonNullable<RawRunnerConfigFile['ai']>,
+): AiAccumulator {
+  return {
+    aiEnabled: payload.enabled ?? acc.aiEnabled,
+    aiModel: payload.model ?? acc.aiModel,
+    aiTemperature: payload.temperature ?? acc.aiTemperature,
+  };
+}
+
+function applySource(
+  acc: { runner: MutableRunner; ai: AiAccumulator },
+  source: ConfigSource,
+): { runner: MutableRunner; ai: AiAccumulator } {
+  const payload = source.load();
+  return {
+    runner: payload.runner
+      ? applyRunnerPayload(acc.runner, payload.runner)
+      : acc.runner,
+    ai: payload.ai ? applyAiPayload(acc.ai, payload.ai) : acc.ai,
+  };
+}
+
+export class RunnerConfigLoader {
+  constructor(private readonly sources: readonly ConfigSource[]) {}
+
+  resolveOptions(): ResolvedRunnerConfigPartial {
+    const ordered = [...this.sources].sort((a, b) => a.priority - b.priority);
+
+    const initial = {
+      runner: {
+        headless: BUILT_IN_DEFAULTS.runner.headless ?? true,
+        outputDir: BUILT_IN_DEFAULTS.runner.outputDir ?? './leak-reports/',
+        topN: BUILT_IN_DEFAULTS.runner.topN ?? 5,
+      },
+      ai: {
+        aiEnabled: BUILT_IN_DEFAULTS.ai.enabled ?? false,
+        aiModel: BUILT_IN_DEFAULTS.ai.model ?? 'Claude3.7',
+        aiTemperature: BUILT_IN_DEFAULTS.ai.temperature ?? 0.3,
+      },
+    };
+
+    const resolved = ordered.reduce(applySource, initial);
+
+    return {
+      runner: resolved.runner,
+      aiEnabled: resolved.ai.aiEnabled,
+      aiModel: resolved.ai.aiModel,
+      aiTemperature: resolved.ai.aiTemperature,
+    };
+  }
+}

package/lib/config/runnerConfigSchema.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const runnerOptionsSchema = z
+  .object({
+    headless: z.boolean(),
+    outputDir: z.string().min(1),
+    topN: z.number().int().min(1),
+  })
+  .partial();
+
+export const aiConfigFileSchema = z
+  .object({
+    enabled: z.boolean(),
+    model: z.string().min(1),
+    temperature: z.number().min(0).max(2),
+  })
+  .partial();
+
+export const runnerConfigFileSchema = z
+  .object({
+    runner: runnerOptionsSchema,
+    ai: aiConfigFileSchema,
+  })
+  .partial()
+  .strict();
+
+export type RawRunnerConfigFile = z.infer<typeof runnerConfigFileSchema>;

package/lib/config/sources/cliOverrideConfigSource.ts

@@ -0,0 +1,30 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+
+export interface CliRunnerOverrides {
+  headless?: boolean;
+  outputDir?: string;
+  topN?: number;
+}
+
+export class CliOverrideConfigSource implements ConfigSource {
+  readonly priority = 3;
+
+  readonly name = 'cli';
+
+  constructor(private readonly overrides: CliRunnerOverrides) {}
+
+  load(): Partial<RawRunnerConfigFile> {
+    const runner: NonNullable<RawRunnerConfigFile['runner']> = {};
+    if (this.overrides.headless !== undefined) {
+      runner.headless = this.overrides.headless;
+    }
+    if (this.overrides.outputDir !== undefined) {
+      runner.outputDir = this.overrides.outputDir;
+    }
+    if (this.overrides.topN !== undefined) {
+      runner.topN = this.overrides.topN;
+    }
+    return Object.keys(runner).length === 0 ? {} : { runner };
+  }
+}

package/lib/config/sources/configSource.ts

@@ -0,0 +1,27 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+
+/**
+ * Strategy interface — each source produces a partial config payload.
+ * Higher `priority` overrides lower when merged by `RunnerConfigLoader`.
+ */
+export interface ConfigSource {
+  readonly priority: number;
+  readonly name: string;
+  load(): Partial<RawRunnerConfigFile>;
+}
+
+export const BUILT_IN_DEFAULTS: Required<{
+  runner: NonNullable<RawRunnerConfigFile['runner']>;
+  ai: NonNullable<RawRunnerConfigFile['ai']>;
+}> = {
+  runner: {
+    headless: true,
+    outputDir: './leak-reports/',
+    topN: 5,
+  },
+  ai: {
+    enabled: false,
+    model: 'Claude3.7',
+    temperature: 0.3,
+  },
+};

package/lib/config/sources/envVarConfigSource.ts

@@ -0,0 +1,23 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+
+export class EnvVarConfigSource implements ConfigSource {
+  readonly priority = 2;
+
+  readonly name = 'env';
+
+  load(): Partial<RawRunnerConfigFile> {
+    const runner: NonNullable<RawRunnerConfigFile['runner']> = {};
+    if (process.env.HEADLESS !== undefined) {
+      runner.headless = process.env.HEADLESS !== 'false';
+    }
+    if (process.env.LEAK_OUTPUT_DIR) {
+      runner.outputDir = process.env.LEAK_OUTPUT_DIR;
+    }
+    if (process.env.LEAK_TOP_N) {
+      const parsed = parseInt(process.env.LEAK_TOP_N, 10);
+      if (Number.isFinite(parsed) && parsed > 0) runner.topN = parsed;
+    }
+    return Object.keys(runner).length === 0 ? {} : { runner };
+  }
+}

package/lib/config/sources/fileConfigSource.ts

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import {
+  runnerConfigFileSchema,
+  type RawRunnerConfigFile,
+} from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+
+export class FileConfigSource implements ConfigSource {
+  readonly priority = 1;
+
+  readonly name = 'file';
+
+  constructor(private readonly filePath: string) {}
+
+  load(): Partial<RawRunnerConfigFile> {
+    if (!fs.existsSync(this.filePath)) return {};
+
+    const raw = fs.readFileSync(this.filePath, 'utf8');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse config file ${this.filePath}: ${
+          (err as Error).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}:\n${issues}`);
+    }
+    return result.data;
+  }
+}

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

@@ -0,0 +1,25 @@
+import { CliOverrideConfigSource } from '../sources/cliOverrideConfigSource.js';
+
+describe('CliOverrideConfigSource', () => {
+  it('returns empty when no overrides are supplied', () => {
+    expect(new CliOverrideConfigSource({}).load()).toEqual({});
+  });
+
+  it('passes through headless when supplied', () => {
+    expect(new CliOverrideConfigSource({ headless: false }).load()).toEqual({
+      runner: { headless: false },
+    });
+  });
+
+  it('passes through outputDir and topN when supplied', () => {
+    expect(
+      new CliOverrideConfigSource({ outputDir: './out/', topN: 8 }).load(),
+    ).toEqual({
+      runner: { outputDir: './out/', topN: 8 },
+    });
+  });
+
+  it('exposes priority 3 (highest tier)', () => {
+    expect(new CliOverrideConfigSource({}).priority).toBe(3);
+  });
+});

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

@@ -0,0 +1,57 @@
+import { EnvVarConfigSource } from '../sources/envVarConfigSource.js';
+
+describe('EnvVarConfigSource', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.HEADLESS;
+    delete process.env.LEAK_OUTPUT_DIR;
+    delete process.env.LEAK_TOP_N;
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('returns empty when no relevant env vars are set', () => {
+    expect(new EnvVarConfigSource().load()).toEqual({});
+  });
+
+  it('parses HEADLESS=false as headless: false', () => {
+    process.env.HEADLESS = 'false';
+    expect(new EnvVarConfigSource().load()).toEqual({
+      runner: { headless: false },
+    });
+  });
+
+  it('parses HEADLESS=true as headless: true', () => {
+    process.env.HEADLESS = 'true';
+    expect(new EnvVarConfigSource().load()).toEqual({
+      runner: { headless: true },
+    });
+  });
+
+  it('reads LEAK_OUTPUT_DIR into runner.outputDir', () => {
+    process.env.LEAK_OUTPUT_DIR = './tmp/out/';
+    expect(new EnvVarConfigSource().load()).toEqual({
+      runner: { outputDir: './tmp/out/' },
+    });
+  });
+
+  it('parses LEAK_TOP_N as an integer', () => {
+    process.env.LEAK_TOP_N = '7';
+    expect(new EnvVarConfigSource().load()).toEqual({
+      runner: { topN: 7 },
+    });
+  });
+
+  it('ignores LEAK_TOP_N when it is not a positive integer', () => {
+    process.env.LEAK_TOP_N = 'banana';
+    expect(new EnvVarConfigSource().load()).toEqual({});
+  });
+
+  it('exposes priority 2 (above file)', () => {
+    expect(new EnvVarConfigSource().priority).toBe(2);
+  });
+});