@elliemae/encw-leak-runner 1.0.13 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +63 -0
  3. package/dist/.tsbuildinfo +1 -1
  4. package/dist/bin/leak-runner.js +258 -29
  5. package/dist/cjs/browser/heapMemoryProfiler.js +182 -0
  6. package/dist/cjs/browser/iframeHeapProfiler.js +2 -2
  7. package/dist/cjs/index.js +2 -0
  8. package/dist/cjs/runner/scenarioRunner.js +9 -6
  9. package/dist/cjs/scenarios/index.js +7 -4
  10. package/dist/cjs/scenarios/one-admin/index.js +5 -1
  11. package/dist/cjs/scenarios/pipeline/index.js +31 -0
  12. package/dist/cjs/scenarios/pipeline/page-models/PipelinePageModel.js +52 -0
  13. package/dist/cjs/scenarios/pipeline/page-models/index.js +24 -0
  14. package/dist/cjs/scenarios/pipeline/pipeline-task-navigation.scenario.js +56 -0
  15. package/dist/esm/browser/heapMemoryProfiler.js +152 -0
  16. package/dist/esm/browser/iframeHeapProfiler.js +1 -1
  17. package/dist/esm/index.js +2 -0
  18. package/dist/esm/runner/scenarioRunner.js +9 -6
  19. package/dist/esm/scenarios/index.js +8 -5
  20. package/dist/esm/scenarios/one-admin/index.js +5 -1
  21. package/dist/esm/scenarios/pipeline/index.js +11 -0
  22. package/dist/esm/scenarios/pipeline/page-models/PipelinePageModel.js +32 -0
  23. package/dist/esm/scenarios/pipeline/page-models/index.js +4 -0
  24. package/dist/esm/scenarios/pipeline/pipeline-task-navigation.scenario.js +36 -0
  25. package/dist/types/lib/browser/heapMemoryProfiler.d.ts +149 -0
  26. package/dist/types/lib/browser/iframeHeapProfiler.d.ts +1 -1
  27. package/dist/types/lib/browser/tests/heapMemoryProfiler.test.d.ts +1 -0
  28. package/dist/types/lib/config/runnerConfigSchema.d.ts +6 -6
  29. package/dist/types/lib/index.d.ts +2 -0
  30. package/dist/types/lib/scenarios/one-admin/index.d.ts +2 -2
  31. package/dist/types/lib/scenarios/pipeline/index.d.ts +2 -0
  32. package/dist/types/lib/scenarios/pipeline/page-models/PipelinePageModel.d.ts +14 -0
  33. package/dist/types/lib/scenarios/pipeline/page-models/index.d.ts +1 -0
  34. package/dist/types/lib/scenarios/pipeline/pipeline-task-navigation.scenario.d.ts +2 -0
  35. package/leak-runner.config.json +1 -1
  36. package/lib/browser/heapMemoryProfiler.ts +284 -0
  37. package/lib/browser/iframeHeapProfiler.ts +1 -1
  38. package/lib/browser/tests/heapMemoryProfiler.test.ts +64 -0
  39. package/lib/browser/tests/iframeHeapProfiler.test.ts +1 -1
  40. package/lib/index.ts +2 -0
  41. package/lib/runner/scenarioRunner.ts +9 -6
  42. package/lib/scenarios/index.ts +8 -6
  43. package/lib/scenarios/one-admin/index.ts +7 -1
  44. package/lib/scenarios/pipeline/index.ts +12 -0
  45. package/lib/scenarios/pipeline/page-models/PipelinePageModel.ts +46 -0
  46. package/lib/scenarios/pipeline/page-models/index.ts +1 -0
  47. package/lib/scenarios/pipeline/pipeline-task-navigation.scenario.ts +42 -0
  48. package/package.json +5 -4
  49. package/reports/analysis/index.html +1 -1
  50. package/reports/analysis/thresholdEvaluator.ts.html +1 -1
  51. package/reports/browser/heapMemoryProfiler.ts.html +937 -0
  52. package/reports/browser/iframeHeapProfiler.ts.html +5 -5
  53. package/reports/browser/index.html +25 -10
  54. package/reports/cli/commands/index.html +1 -1
  55. package/reports/cli/commands/listCommand.ts.html +1 -1
  56. package/reports/cli/commands/runCommand.ts.html +1 -1
  57. package/reports/cli/index.html +1 -1
  58. package/reports/cli/index.ts.html +1 -1
  59. package/reports/config/index.html +1 -1
  60. package/reports/config/missingRequiredParamError.ts.html +1 -1
  61. package/reports/config/requiredEnvParams.ts.html +1 -1
  62. package/reports/config/runnerConfigLoader.ts.html +1 -1
  63. package/reports/config/runnerConfigSchema.ts.html +1 -1
  64. package/reports/config/sources/cliOverrideConfigSource.ts.html +1 -1
  65. package/reports/config/sources/configSource.ts.html +1 -1
  66. package/reports/config/sources/envVarConfigSource.ts.html +1 -1
  67. package/reports/config/sources/fileConfigSource.ts.html +1 -1
  68. package/reports/config/sources/index.html +1 -1
  69. package/reports/config/unknownEnvError.ts.html +1 -1
  70. package/reports/index.html +63 -33
  71. package/reports/lcov-report/analysis/index.html +1 -1
  72. package/reports/lcov-report/analysis/thresholdEvaluator.ts.html +1 -1
  73. package/reports/lcov-report/browser/heapMemoryProfiler.ts.html +937 -0
  74. package/reports/lcov-report/browser/iframeHeapProfiler.ts.html +5 -5
  75. package/reports/lcov-report/browser/index.html +25 -10
  76. package/reports/lcov-report/cli/commands/index.html +1 -1
  77. package/reports/lcov-report/cli/commands/listCommand.ts.html +1 -1
  78. package/reports/lcov-report/cli/commands/runCommand.ts.html +1 -1
  79. package/reports/lcov-report/cli/index.html +1 -1
  80. package/reports/lcov-report/cli/index.ts.html +1 -1
  81. package/reports/lcov-report/config/index.html +1 -1
  82. package/reports/lcov-report/config/missingRequiredParamError.ts.html +1 -1
  83. package/reports/lcov-report/config/requiredEnvParams.ts.html +1 -1
  84. package/reports/lcov-report/config/runnerConfigLoader.ts.html +1 -1
  85. package/reports/lcov-report/config/runnerConfigSchema.ts.html +1 -1
  86. package/reports/lcov-report/config/sources/cliOverrideConfigSource.ts.html +1 -1
  87. package/reports/lcov-report/config/sources/configSource.ts.html +1 -1
  88. package/reports/lcov-report/config/sources/envVarConfigSource.ts.html +1 -1
  89. package/reports/lcov-report/config/sources/fileConfigSource.ts.html +1 -1
  90. package/reports/lcov-report/config/sources/index.html +1 -1
  91. package/reports/lcov-report/config/unknownEnvError.ts.html +1 -1
  92. package/reports/lcov-report/index.html +63 -33
  93. package/reports/lcov-report/registry/index.html +1 -1
  94. package/reports/lcov-report/registry/scenarioRegistry.ts.html +1 -1
  95. package/reports/lcov-report/reporting/consoleReporter.ts.html +1 -1
  96. package/reports/lcov-report/reporting/index.html +1 -1
  97. package/reports/lcov-report/reporting/junitReporter.ts.html +1 -1
  98. package/reports/lcov-report/runner/aiEnhancementStep.ts.html +1 -1
  99. package/reports/lcov-report/runner/batchRunner.ts.html +1 -1
  100. package/reports/lcov-report/runner/index.html +15 -15
  101. package/reports/lcov-report/runner/scenarioRunner.ts.html +23 -14
  102. package/reports/lcov-report/scenarios/index.html +8 -8
  103. package/reports/lcov-report/scenarios/index.ts.html +20 -14
  104. package/reports/lcov-report/scenarios/one-admin/export-navigation.scenario.ts.html +1 -1
  105. package/reports/lcov-report/scenarios/one-admin/index.html +5 -5
  106. package/reports/lcov-report/scenarios/one-admin/index.ts.html +24 -6
  107. package/reports/lcov-report/scenarios/one-admin/page-models/AdminLandingPageModel.ts.html +1 -1
  108. package/reports/lcov-report/scenarios/one-admin/page-models/ExportPageModel.ts.html +1 -1
  109. package/reports/lcov-report/scenarios/one-admin/page-models/SelectSettingsPageModel.ts.html +1 -1
  110. package/reports/lcov-report/scenarios/one-admin/page-models/index.html +1 -1
  111. package/reports/lcov-report/scenarios/pipeline/index.html +131 -0
  112. package/reports/lcov-report/scenarios/pipeline/index.ts.html +121 -0
  113. package/reports/lcov-report/scenarios/pipeline/page-models/PipelinePageModel.ts.html +223 -0
  114. package/reports/lcov-report/scenarios/pipeline/page-models/index.html +116 -0
  115. package/reports/lcov-report/scenarios/pipeline/pipeline-task-navigation.scenario.ts.html +211 -0
  116. package/reports/lcov-report/types/config.ts.html +1 -1
  117. package/reports/lcov-report/types/index.html +1 -1
  118. package/reports/lcov.info +225 -40
  119. package/reports/registry/index.html +1 -1
  120. package/reports/registry/scenarioRegistry.ts.html +1 -1
  121. package/reports/reporting/consoleReporter.ts.html +1 -1
  122. package/reports/reporting/index.html +1 -1
  123. package/reports/reporting/junitReporter.ts.html +1 -1
  124. package/reports/runner/aiEnhancementStep.ts.html +1 -1
  125. package/reports/runner/batchRunner.ts.html +1 -1
  126. package/reports/runner/index.html +15 -15
  127. package/reports/runner/scenarioRunner.ts.html +23 -14
  128. package/reports/scenarios/index.html +8 -8
  129. package/reports/scenarios/index.ts.html +20 -14
  130. package/reports/scenarios/one-admin/export-navigation.scenario.ts.html +1 -1
  131. package/reports/scenarios/one-admin/index.html +5 -5
  132. package/reports/scenarios/one-admin/index.ts.html +24 -6
  133. package/reports/scenarios/one-admin/page-models/AdminLandingPageModel.ts.html +1 -1
  134. package/reports/scenarios/one-admin/page-models/ExportPageModel.ts.html +1 -1
  135. package/reports/scenarios/one-admin/page-models/SelectSettingsPageModel.ts.html +1 -1
  136. package/reports/scenarios/one-admin/page-models/index.html +1 -1
  137. package/reports/scenarios/pipeline/index.html +131 -0
  138. package/reports/scenarios/pipeline/index.ts.html +121 -0
  139. package/reports/scenarios/pipeline/page-models/PipelinePageModel.ts.html +223 -0
  140. package/reports/scenarios/pipeline/page-models/index.html +116 -0
  141. package/reports/scenarios/pipeline/pipeline-task-navigation.scenario.ts.html +211 -0
  142. package/reports/types/config.ts.html +1 -1
  143. package/reports/types/index.html +1 -1
  144. package/test-report.xml +66 -62
@@ -4,13 +4,13 @@ export declare const runnerOptionsSchema: z.ZodObject<{
4
4
  outputDir: z.ZodOptional<z.ZodString>;
5
5
  topN: z.ZodOptional<z.ZodNumber>;
6
6
  }, "strip", z.ZodTypeAny, {
7
+ topN?: number | undefined;
7
8
  headless?: boolean | undefined;
8
9
  outputDir?: string | undefined;
9
- topN?: number | undefined;
10
10
  }, {
11
+ topN?: number | undefined;
11
12
  headless?: boolean | undefined;
12
13
  outputDir?: string | undefined;
13
- topN?: number | undefined;
14
14
  }>;
15
15
  export declare const aiConfigFileSchema: z.ZodObject<{
16
16
  enabled: z.ZodOptional<z.ZodBoolean>;
@@ -33,13 +33,13 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
33
33
  outputDir: z.ZodOptional<z.ZodString>;
34
34
  topN: z.ZodOptional<z.ZodNumber>;
35
35
  }, "strip", z.ZodTypeAny, {
36
+ topN?: number | undefined;
36
37
  headless?: boolean | undefined;
37
38
  outputDir?: string | undefined;
38
- topN?: number | undefined;
39
39
  }, {
40
+ topN?: number | undefined;
40
41
  headless?: boolean | undefined;
41
42
  outputDir?: string | undefined;
42
- topN?: number | undefined;
43
43
  }>>;
44
44
  ai: z.ZodOptional<z.ZodObject<{
45
45
  enabled: z.ZodOptional<z.ZodBoolean>;
@@ -58,9 +58,9 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
58
58
  }, "strict", z.ZodTypeAny, {
59
59
  $schema?: string | undefined;
60
60
  runner?: {
61
+ topN?: number | undefined;
61
62
  headless?: boolean | undefined;
62
63
  outputDir?: string | undefined;
63
- topN?: number | undefined;
64
64
  } | undefined;
65
65
  ai?: {
66
66
  enabled?: boolean | undefined;
@@ -71,9 +71,9 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
71
71
  }, {
72
72
  $schema?: string | undefined;
73
73
  runner?: {
74
+ topN?: number | undefined;
74
75
  headless?: boolean | undefined;
75
76
  outputDir?: string | undefined;
76
- topN?: number | undefined;
77
77
  } | undefined;
78
78
  ai?: {
79
79
  enabled?: boolean | undefined;
@@ -6,6 +6,8 @@ export type { ThresholdResult, ScenarioResult, RunSummary, } from './types/resul
6
6
  export { ScenarioRegistry } from './registry/scenarioRegistry.js';
7
7
  export { BatchRunner } from './runner/batchRunner.js';
8
8
  export { ScenarioRunner } from './runner/scenarioRunner.js';
9
+ export { HeapMemoryProfiler } from './browser/heapMemoryProfiler.js';
10
+ export type { HeapProfilingOptions } from './browser/heapMemoryProfiler.js';
9
11
  export { IframeHeapProfiler } from './browser/iframeHeapProfiler.js';
10
12
  export { ThresholdEvaluator } from './analysis/thresholdEvaluator.js';
11
13
  export { ConsoleReporter } from './reporting/consoleReporter.js';
@@ -1,2 +1,2 @@
1
- import type { MicroappLeakScenario } from '../../types/scenario.js';
2
- export declare const oneAdminScenarios: readonly MicroappLeakScenario[];
1
+ import type { ScenarioGroup } from '../../registry/scenarioRegistry.js';
2
+ export declare const oneAdminScenarioGroup: ScenarioGroup;
@@ -0,0 +1,2 @@
1
+ import type { ScenarioGroup } from 'lib/registry/scenarioRegistry.js';
2
+ export declare const pipelineScenarioGroup: ScenarioGroup;
@@ -0,0 +1,14 @@
1
+ import type { Page } from '@playwright/test';
2
+ export declare class PipelinePageModel {
3
+ #private;
4
+ private readonly page;
5
+ static readonly IFRAME_SELECTOR = "[data-testid=\"pui-iframe-container-pipelineui\"]";
6
+ private static readonly TASKS_IFRAME_SELECTOR;
7
+ private static readonly SPINNER_TEST_ID;
8
+ constructor(page: Page);
9
+ waitForPipelineReady(): Promise<void>;
10
+ clickTasksTab(): Promise<void>;
11
+ clickPipelineTab(): Promise<void>;
12
+ waitForPipelineSpinner(): Promise<void>;
13
+ waitForTasksReady(): Promise<void>;
14
+ }
@@ -0,0 +1 @@
1
+ export { PipelinePageModel } from './PipelinePageModel.js';
@@ -0,0 +1,2 @@
1
+ import type { MicroappLeakScenario } from '../../types/scenario.js';
2
+ export declare const pipelineTaskNavigationScenario: MicroappLeakScenario;
@@ -3,7 +3,7 @@
3
3
  "runner": {
4
4
  "headless": true,
5
5
  "outputDir": "./leak-reports/",
6
- "topN": 5
6
+ "topN": 10
7
7
  },
8
8
  "ai": {
9
9
  "enabled": false,
@@ -0,0 +1,284 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import type { Page, Frame } from '@playwright/test';
4
+ import { HeapDoctor } from '@elliemae/encw-heap-doctor';
5
+ import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
6
+
7
+ export interface HeapProfilingOptions {
8
+ /**
9
+ * Number of times to execute the flow between the before and after snapshots.
10
+ * More iterations amplify the leak signal — a leak of N bytes per run becomes
11
+ * N × heapIterations in the delta, making small leaks detectable above GC noise.
12
+ * Default: 1.
13
+ */
14
+ heapIterations?: number;
15
+
16
+ /**
17
+ * Label prefix used in snapshot filenames and as the Memento key.
18
+ * Two files are written: `<label>-before-<epoch>.heapsnapshot` and
19
+ * `<label>-after-<epoch>.heapsnapshot`.
20
+ * Default: 'flow'.
21
+ */
22
+ label?: string;
23
+
24
+ /**
25
+ * Number of top leak groups to include in the HeapDoctor report.
26
+ * Default: 5 (HeapDoctor default).
27
+ */
28
+ topN?: number;
29
+
30
+ /**
31
+ * When `true`, throws after comparison if `retainedSizeDelta` exceeds
32
+ * {@link leakThresholdBytes}, causing the Playwright test to fail.
33
+ * Default: false.
34
+ */
35
+ failOnLeak?: boolean;
36
+
37
+ /**
38
+ * Retained-size growth in bytes above which the test is failed when
39
+ * {@link failOnLeak} is `true`. Set to 0 to fail on any positive delta.
40
+ * Default: 0.
41
+ */
42
+ leakThresholdBytes?: number;
43
+
44
+ /**
45
+ * Optional allow-list of `Window` origins (e.g. `'https://encompass.q3.ice.com'`).
46
+ *
47
+ * Forwarded to `HeapDoctor`; suppresses retainer chains rooted in unrelated
48
+ * same-site iframes (e.g. partner plugins) that share the main V8 isolate.
49
+ * Chains with no `Window` step are always kept.
50
+ */
51
+ originAllowList?: readonly string[];
52
+ }
53
+
54
+ /** Parameters for {@link HeapMemoryProfiler.compare}. */
55
+ export interface CompareParams {
56
+ /** Label passed to `captureSnapshot()` for the baseline. */
57
+ beforeLabel: string;
58
+ /** Label passed to `captureSnapshot()` for the post-flow snapshot. */
59
+ afterLabel: string;
60
+ /** Override for the number of top leak groups in the report. */
61
+ topN?: number;
62
+ /** Allow-list of `Window` origins; forwarded to `HeapDoctor`. */
63
+ originAllowList?: readonly string[];
64
+ }
65
+
66
+ /**
67
+ * Encapsulates heap memory profiling for a single Playwright test.
68
+ *
69
+ * **Responsibilities:**
70
+ * - CDP session lifecycle (open, stream chunks, detach)
71
+ * - `.heapsnapshot` file I/O
72
+ * - Snapshot label cache (Memento store, cleared per test)
73
+ * - HeapDoctor comparison and markdown report writing
74
+ * - Optional test failure on leak threshold breach
75
+ *
76
+ * **Usage:**
77
+ * ```ts
78
+ * class MySpec extends AdminBaseTest {
79
+ * private heapProfiler!: HeapMemoryProfiler;
80
+ *
81
+ * async beforeEach() {
82
+ * await super.beforeEach();
83
+ * this.heapProfiler = new HeapMemoryProfiler(this.page, 'reports/heap-snapshots/my-spec');
84
+ * }
85
+ *
86
+ * async afterEach() {
87
+ * this.heapProfiler.clearSnapshots();
88
+ * await super.afterEach();
89
+ * }
90
+ *
91
+ * async testFlow_Memory() {
92
+ * await this.goto('some.route');
93
+ * await this.heapProfiler.withProfiling(async () => {
94
+ * await this.somePage.doSomething();
95
+ * }, { heapIterations: 3, label: 'my-flow', failOnLeak: true, leakThresholdBytes: 500_000 });
96
+ * }
97
+ * }
98
+ * ```
99
+ *
100
+ * **Non-Chromium:** All methods silently no-op and return `null` / empty string.
101
+ * The flow inside `withProfiling` still executes normally.
102
+ */
103
+ export class HeapMemoryProfiler {
104
+ /** Memento store: maps snapshot label → absolute file path on disk. */
105
+ private readonly snapshots = new Map<string, string>();
106
+
107
+ /**
108
+ * @param {Page} page - The Playwright `Page` instance for the current test.
109
+ * @param {string} outputDir - Directory where `.heapsnapshot` and `.md` files are written.
110
+ * Created automatically if it does not exist.
111
+ */
112
+ constructor(
113
+ private readonly page: Page,
114
+ private readonly outputDir: string,
115
+ ) {}
116
+
117
+ protected getCDPTarget(): Page | Frame {
118
+ return this.page;
119
+ }
120
+
121
+ // ─── Browser guard ──────────────────────────────────────────────────────────
122
+
123
+ private isChromium(): boolean {
124
+ return this.page.context().browser()?.browserType().name() === 'chromium';
125
+ }
126
+
127
+ // ─── Public API ─────────────────────────────────────────────────────────────
128
+
129
+ /**
130
+ * Capture a Chrome heap snapshot via CDP and persist it to disk.
131
+ *
132
+ * The snapshot is streamed in chunks via `HeapProfiler.addHeapSnapshotChunk`,
133
+ * joined, and written as a single `.heapsnapshot` file. The file path is cached
134
+ * internally under `label` so {@link compare} can resolve it by name.
135
+ * @param {string} label - Logical name for this snapshot (e.g. `'before'`, `'after'`).
136
+ * Used as the filename prefix and as the Memento key.
137
+ * @returns {Promise<string>} Absolute path to the written file, or `''` on non-Chromium browsers.
138
+ */
139
+ async captureSnapshot(label: string): Promise<string> {
140
+ if (!this.isChromium()) return '';
141
+
142
+ const client = await this.page.context().newCDPSession(this.getCDPTarget());
143
+ await client.send('HeapProfiler.enable');
144
+
145
+ fs.mkdirSync(this.outputDir, { recursive: true });
146
+ const filePath = path.join(
147
+ this.outputDir,
148
+ `${label}-${Date.now()}.heapsnapshot`,
149
+ );
150
+ const writeStream = fs.createWriteStream(filePath);
151
+
152
+ client.on(
153
+ 'HeapProfiler.addHeapSnapshotChunk',
154
+ ({ chunk }: { chunk: string }) => {
155
+ writeStream.write(chunk);
156
+ },
157
+ );
158
+
159
+ await client.send('HeapProfiler.takeHeapSnapshot', {
160
+ reportProgress: false,
161
+ });
162
+ await client.send('HeapProfiler.disable');
163
+ await client.detach();
164
+
165
+ await new Promise<void>((resolve, reject) => {
166
+ writeStream.end((err?: Error | null) => {
167
+ if (err) reject(err);
168
+ else resolve();
169
+ });
170
+ });
171
+
172
+ this.snapshots.set(label, filePath);
173
+ return filePath;
174
+ }
175
+
176
+ /**
177
+ * Compare two previously captured snapshots by their labels.
178
+ *
179
+ * Runs `HeapDoctor.compare()` on the resolved file paths and writes a
180
+ * markdown report to {@link outputDir}.
181
+ * @param {CompareParams} params - {@link CompareParams}
182
+ * @returns {Promise<ComparisonReport | null>} `ComparisonReport`, or `null` on non-Chromium browsers.
183
+ * @throws If either label has no cached snapshot path.
184
+ * @throws If `HeapDoctor.compare` returns `ok: false`.
185
+ */
186
+ async compare(params: CompareParams): Promise<ComparisonReport | null> {
187
+ const { beforeLabel, afterLabel, topN, originAllowList } = params;
188
+ if (!this.isChromium()) return null;
189
+
190
+ const before = this.snapshots.get(beforeLabel);
191
+ const after = this.snapshots.get(afterLabel);
192
+
193
+ if (!before || !after) {
194
+ throw new Error(
195
+ `HeapMemoryProfiler: snapshot not found for labels "${beforeLabel}" / "${afterLabel}". ` +
196
+ `Call captureSnapshot() before compare().`,
197
+ );
198
+ }
199
+
200
+ const result = await new HeapDoctor({ topN, originAllowList }).compare(
201
+ before,
202
+ after,
203
+ );
204
+ if (!result.ok) throw result.error;
205
+
206
+ fs.writeFileSync(
207
+ path.join(this.outputDir, `comparison-${Date.now()}.md`),
208
+ result.value.markdown,
209
+ );
210
+
211
+ return result.value;
212
+ }
213
+
214
+ /**
215
+ * Orchestrate the full heap profiling sequence for a user flow.
216
+ *
217
+ * Sequence (Template Method):
218
+ * 1. Capture **before** snapshot
219
+ * 2. Execute `flow` exactly `heapIterations` times
220
+ * 3. Capture **after** snapshot
221
+ * 4. Run `HeapDoctor.compare` and write the markdown report
222
+ * 5. If `failOnLeak` is `true` and `retainedSizeDelta > leakThresholdBytes`, throw
223
+ *
224
+ * On non-Chromium browsers: `flow` still runs `heapIterations` times,
225
+ * no snapshots are taken, and `null` is returned.
226
+ * @param {() => Promise<void>} flow - Async function containing the user actions to profile.
227
+ * @param {HeapProfilingOptions} [options] - {@link HeapProfilingOptions}
228
+ * @returns {Promise<ComparisonReport | null>} `ComparisonReport` on Chromium, `null` on all other browsers.
229
+ */
230
+ async withProfiling(
231
+ flow: () => Promise<void>,
232
+ options: HeapProfilingOptions = {},
233
+ ): Promise<ComparisonReport | null> {
234
+ const {
235
+ heapIterations = 1,
236
+ label = 'flow',
237
+ topN,
238
+ failOnLeak = false,
239
+ leakThresholdBytes = 0,
240
+ originAllowList,
241
+ } = options;
242
+
243
+ if (!this.isChromium()) {
244
+ // eslint-disable-next-line no-await-in-loop
245
+ for (let i = 0; i < heapIterations; i += 1) await flow();
246
+ return null;
247
+ }
248
+
249
+ await this.captureSnapshot(`${label}-before`);
250
+ // eslint-disable-next-line no-await-in-loop
251
+ for (let i = 0; i < heapIterations; i += 1) await flow();
252
+ await this.captureSnapshot(`${label}-after`);
253
+
254
+ const report = await this.compare({
255
+ beforeLabel: `${label}-before`,
256
+ afterLabel: `${label}-after`,
257
+ topN,
258
+ originAllowList,
259
+ });
260
+
261
+ if (
262
+ report &&
263
+ failOnLeak &&
264
+ report.delta.retainedSizeDelta > leakThresholdBytes
265
+ ) {
266
+ throw new Error(
267
+ `Memory leak detected: retained size grew by ${report.delta.retainedSizeDelta} bytes ` +
268
+ `(threshold: ${leakThresholdBytes} bytes). ` +
269
+ `New leak groups: ${report.delta.newLeakGroups.length}. ` +
270
+ `See: ${this.outputDir}`,
271
+ );
272
+ }
273
+
274
+ return report;
275
+ }
276
+
277
+ /**
278
+ * Clear the internal snapshot label cache.
279
+ * Call in `afterEach` to prevent snapshot paths bleeding across tests.
280
+ */
281
+ clearSnapshots(): void {
282
+ this.snapshots.clear();
283
+ }
284
+ }
@@ -1,5 +1,5 @@
1
- import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
2
1
  import type { Page, Frame } from '@playwright/test';
2
+ import { HeapMemoryProfiler } from './heapMemoryProfiler.js';
3
3
 
4
4
  export class IframeHeapProfiler extends HeapMemoryProfiler {
5
5
  constructor(
@@ -0,0 +1,64 @@
1
+ import type { Page, Frame } from '@playwright/test';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import os from 'node:os';
5
+ import { HeapMemoryProfiler } from '../heapMemoryProfiler.js';
6
+
7
+ describe('HeapMemoryProfiler — Template Method', () => {
8
+ it('allows subclass to override getCDPTarget', () => {
9
+ const mockPage = {
10
+ context: () => ({
11
+ browser: () => ({ browserType: () => ({ name: () => 'chromium' }) }),
12
+ newCDPSession: jest.fn().mockResolvedValue({
13
+ send: jest.fn().mockResolvedValue(undefined),
14
+ on: jest.fn(),
15
+ detach: jest.fn().mockResolvedValue(undefined),
16
+ }),
17
+ }),
18
+ } as unknown as Page;
19
+
20
+ const profiler = new HeapMemoryProfiler(mockPage, '/tmp/test-heap');
21
+ expect(profiler).toBeInstanceOf(HeapMemoryProfiler);
22
+ });
23
+
24
+ it('passes the overridden target to newCDPSession when subclass overrides getCDPTarget', async () => {
25
+ const sentinelFrame = {} as Frame;
26
+ let receivedTarget: Page | Frame | undefined;
27
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'heap-test-'));
28
+
29
+ const mockPage = {
30
+ context: () => ({
31
+ browser: () => ({ browserType: () => ({ name: () => 'chromium' }) }),
32
+ newCDPSession: (target: Page | Frame) => {
33
+ receivedTarget = target;
34
+ const chunks: Array<(event: { chunk: string }) => void> = [];
35
+ return Promise.resolve({
36
+ send: (method: string) => {
37
+ if (method === 'HeapProfiler.takeHeapSnapshot') {
38
+ chunks.forEach((cb) => cb({ chunk: '{}' }));
39
+ }
40
+ return Promise.resolve();
41
+ },
42
+ on: (_: string, cb: (event: { chunk: string }) => void) => {
43
+ chunks.push(cb);
44
+ },
45
+ detach: () => Promise.resolve(),
46
+ });
47
+ },
48
+ }),
49
+ } as unknown as Page;
50
+
51
+ class TestProfiler extends HeapMemoryProfiler {
52
+ protected override getCDPTarget(): Page | Frame {
53
+ return sentinelFrame;
54
+ }
55
+ }
56
+
57
+ const profiler = new TestProfiler(mockPage, tmpDir);
58
+ await profiler.captureSnapshot('test');
59
+
60
+ fs.rmSync(tmpDir, { recursive: true, force: true });
61
+
62
+ expect(receivedTarget).toBe(sentinelFrame);
63
+ });
64
+ });
@@ -1,5 +1,5 @@
1
- import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
2
1
  import type { Page, Frame } from '@playwright/test';
2
+ import { HeapMemoryProfiler } from '../heapMemoryProfiler.js';
3
3
  import { IframeHeapProfiler } from '../iframeHeapProfiler.js';
4
4
 
5
5
  // `getCDPTarget` is protected on the real classes; tests need structural access.
package/lib/index.ts CHANGED
@@ -22,6 +22,8 @@ export type {
22
22
  export { ScenarioRegistry } from './registry/scenarioRegistry.js';
23
23
  export { BatchRunner } from './runner/batchRunner.js';
24
24
  export { ScenarioRunner } from './runner/scenarioRunner.js';
25
+ export { HeapMemoryProfiler } from './browser/heapMemoryProfiler.js';
26
+ export type { HeapProfilingOptions } from './browser/heapMemoryProfiler.js';
25
27
  export { IframeHeapProfiler } from './browser/iframeHeapProfiler.js';
26
28
  export { ThresholdEvaluator } from './analysis/thresholdEvaluator.js';
27
29
  export { ConsoleReporter } from './reporting/consoleReporter.js';
@@ -96,11 +96,12 @@ export class ScenarioRunner {
96
96
  await forceGarbageCollection(page);
97
97
  paths.after = await profiler.captureSnapshot('after');
98
98
 
99
- const report = await profiler.compare(
100
- 'before',
101
- 'after',
102
- this.config.runner.topN,
103
- );
99
+ const report = await profiler.compare({
100
+ beforeLabel: 'before',
101
+ afterLabel: 'after',
102
+ topN: this.config.runner.topN,
103
+ originAllowList: [new URL(this.config.env.baseUrl).origin],
104
+ });
104
105
  if (report) await this.writeReport(report, scenario);
105
106
  return report;
106
107
  }
@@ -121,7 +122,9 @@ export class ScenarioRunner {
121
122
  instanceId: this.config.env.instanceId,
122
123
  });
123
124
  process.stderr.write(`[scenarioRunner] post-login URL = ${page.url()}\n`);
124
- await page.waitForURL(`**${scenario.url()}**`, { timeout: 30_000 });
125
+ if (!page.url().includes(scenario.url())) {
126
+ await page.goto(scenario.url(), { waitUntil: 'load', timeout: 30_000 });
127
+ }
125
128
  process.stderr.write(
126
129
  `[scenarioRunner] settled URL before iframe = ${page.url()}\n`,
127
130
  );
@@ -1,8 +1,10 @@
1
1
  import { ScenarioRegistry } from '../registry/scenarioRegistry.js';
2
- import { oneAdminScenarios } from './one-admin/index.js';
2
+ import { oneAdminScenarioGroup } from './one-admin/index.js';
3
+ import { pipelineScenarioGroup } from './pipeline/index.js';
3
4
 
4
- export const scenarioRegistry: ScenarioRegistry =
5
- new ScenarioRegistry().register({
6
- microapp: 'one-admin',
7
- scenarios: oneAdminScenarios,
8
- });
5
+ export const scenarioRegistry = ((): ScenarioRegistry => {
6
+ const registry = new ScenarioRegistry();
7
+ registry.register(oneAdminScenarioGroup);
8
+ registry.register(pipelineScenarioGroup);
9
+ return registry;
10
+ })();
@@ -1,6 +1,12 @@
1
+ import type { ScenarioGroup } from '../../registry/scenarioRegistry.js';
1
2
  import type { MicroappLeakScenario } from '../../types/scenario.js';
2
3
  import { exportNavigationScenario } from './export-navigation.scenario.js';
3
4
 
4
- export const oneAdminScenarios: readonly MicroappLeakScenario[] = [
5
+ const oneAdminScenarios: readonly MicroappLeakScenario[] = [
5
6
  exportNavigationScenario,
6
7
  ];
8
+
9
+ export const oneAdminScenarioGroup: ScenarioGroup = {
10
+ microapp: 'one-admin',
11
+ scenarios: oneAdminScenarios,
12
+ };
@@ -0,0 +1,12 @@
1
+ import type { ScenarioGroup } from 'lib/registry/scenarioRegistry.js';
2
+ import type { MicroappLeakScenario } from '../../types/scenario.js';
3
+ import { pipelineTaskNavigationScenario } from './pipeline-task-navigation.scenario.js';
4
+
5
+ const pipelineScenarios: readonly MicroappLeakScenario[] = [
6
+ pipelineTaskNavigationScenario,
7
+ ];
8
+
9
+ export const pipelineScenarioGroup: ScenarioGroup = {
10
+ microapp: 'pipeline',
11
+ scenarios: pipelineScenarios,
12
+ };
@@ -0,0 +1,46 @@
1
+ import type { Page } from '@playwright/test';
2
+
3
+ export class PipelinePageModel {
4
+ static readonly IFRAME_SELECTOR =
5
+ '[data-testid="pui-iframe-container-pipelineui"]';
6
+
7
+ private static readonly TASKS_IFRAME_SELECTOR =
8
+ '[data-testid="pui-iframe-container-taskspipeline"]';
9
+
10
+ private static readonly SPINNER_TEST_ID =
11
+ 'ds-circularindeterminateindicator-svg';
12
+
13
+ constructor(private readonly page: Page) {}
14
+
15
+ async waitForPipelineReady(): Promise<void> {
16
+ await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
17
+ }
18
+
19
+ async clickTasksTab(): Promise<void> {
20
+ await this.page.getByRole('tab', { name: 'Tasks' }).click();
21
+ }
22
+
23
+ async clickPipelineTab(): Promise<void> {
24
+ await this.page.getByRole('tab', { name: 'Loans' }).click();
25
+ }
26
+
27
+ async waitForPipelineSpinner(): Promise<void> {
28
+ await this.#waitForSpinner(PipelinePageModel.IFRAME_SELECTOR);
29
+ }
30
+
31
+ async waitForTasksReady(): Promise<void> {
32
+ await this.page
33
+ .locator(PipelinePageModel.TASKS_IFRAME_SELECTOR)
34
+ .contentFrame()
35
+ .getByTestId('circular-indicator')
36
+ .waitFor({ state: 'hidden' });
37
+ }
38
+
39
+ async #waitForSpinner(iframeSelector: string): Promise<void> {
40
+ const spinner = this.page
41
+ .frameLocator(iframeSelector)
42
+ .getByTestId(PipelinePageModel.SPINNER_TEST_ID);
43
+ await spinner.waitFor({ state: 'visible' });
44
+ await spinner.waitFor({ state: 'hidden' });
45
+ }
46
+ }
@@ -0,0 +1 @@
1
+ export { PipelinePageModel } from './PipelinePageModel.js';
@@ -0,0 +1,42 @@
1
+ import type { MicroappLeakScenario } from '../../types/scenario.js';
2
+ import { AdminLandingPageModel } from '../one-admin/page-models/index.js';
3
+ import { PipelinePageModel } from './page-models/index.js';
4
+
5
+ export const pipelineTaskNavigationScenario: MicroappLeakScenario = {
6
+ id: 'pipeline-task-navigation',
7
+ name: 'Pipeline Task Navigation',
8
+ description:
9
+ 'Navigate to pipeline task details and come back - verify iframe GC',
10
+ tags: ['critical'],
11
+ microappSelector: PipelinePageModel.IFRAME_SELECTOR,
12
+
13
+ url: () => '/pipeline',
14
+
15
+ async setup(page) {
16
+ await AdminLandingPageModel.acceptCookiesIfShown(page);
17
+ const pipeline = new PipelinePageModel(page);
18
+ await pipeline.waitForPipelineReady();
19
+ },
20
+
21
+ async action(page) {
22
+ const pipeline = new PipelinePageModel(page);
23
+ const path = new URL(page.url()).pathname.replace(/\/$/, '');
24
+ if (path === '/pipeline') {
25
+ await pipeline.clickTasksTab();
26
+ }
27
+ await pipeline.waitForTasksReady();
28
+ },
29
+
30
+ async back(page) {
31
+ const pipeline = new PipelinePageModel(page);
32
+ await pipeline.clickPipelineTab();
33
+ await pipeline.waitForPipelineSpinner();
34
+ },
35
+
36
+ repeat: () => 1,
37
+
38
+ thresholds: {
39
+ maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
40
+ maxNewLeakGroups: 0,
41
+ },
42
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elliemae/encw-leak-runner",
3
- "version": "1.0.13",
3
+ "version": "1.0.14",
4
4
  "description": "Playwright orchestration framework for microapp memory leak detection",
5
5
  "type": "module",
6
6
  "main": "./dist/cjs/index.js",
@@ -19,8 +19,8 @@
19
19
  "dependencies": {
20
20
  "commander": "^12.1.0",
21
21
  "zod": "^3.25.76",
22
- "@elliemae/smoked-suite": "26.2.37",
23
- "@elliemae/encw-heap-doctor": "26.2.26"
22
+ "@elliemae/encw-heap-doctor": "26.2.27",
23
+ "@elliemae/smoked-suite": "26.2.38"
24
24
  },
25
25
  "devDependencies": {
26
26
  "@elliemae/pui-cli": "~8.59.3",
@@ -41,6 +41,7 @@
41
41
  "test-watch": "jest --watch",
42
42
  "lint": "pui-cli lint",
43
43
  "lint:fix": "pui-cli lint --fix",
44
- "tscheck": "pui-cli tscheck --files"
44
+ "tscheck": "pui-cli tscheck --files",
45
+ "codegen": "playwright codegen"
45
46
  }
46
47
  }