@memlab/api 1.0.22 → 1.0.24

package/dist/API.d.ts

@@ -13,10 +13,11 @@ import { MemLabConfig } from '@memlab/core';
 import { TestPlanner } from '@memlab/e2e';
 import { BaseAnalysis } from '@memlab/heap-analysis';
 import BrowserInteractionResultReader from './result-reader/BrowserInteractionResultReader';
+import BaseResultReader from './result-reader/BaseResultReader';
 /**
  * Options for configuring browser interaction run, all fields are optional
  */
-export declare type RunOptions = {
+export type RunOptions = {
     /**
      * test scenario specifying how to interact with browser
      * (for more details view {@link IScenario})
@@ -52,11 +53,15 @@ export declare type RunOptions = {
      * means analyzing the heap of the web worker with name: `'workerTitle'`.
      */
     webWorker?: Optional<string>;
+    /**
+     * skip warmup page load for the target web app
+     */
+    skipWarmup?: boolean;
 };
 /**
  * A data structure holding the result of the {@link run} API call.
  */
-export declare type RunResult = {
+export type RunResult = {
     /**
      * leak traces detected and clustered from the browser interaction
      */
@@ -70,7 +75,7 @@ export declare type RunResult = {
  * Options for memlab inter-package API calls
  * @internal
  */
-export declare type APIOptions = {
+export type APIOptions = {
     testPlanner?: TestPlanner;
     cache?: boolean;
     config?: MemLabConfig;
@@ -138,7 +143,7 @@ export declare function run(runOptions?: RunOptions): Promise<RunResult>;
  */
 export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInteractionResultReader>;
 /**
- * This API finds memory leaks by analyzing heap snapshot(s)
+ * This API finds memory leaks by analyzing heap snapshot(s).
  * This is equivalent to `memlab find-leaks` in CLI.
  *
  * @param runResult return value of a browser interaction run
@@ -156,7 +161,22 @@ export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInte
  * })();
  * ```
  */
-export declare function findLeaks(runResult: BrowserInteractionResultReader): Promise<ISerializedInfo[]>;
+export declare function findLeaks(runResult: BaseResultReader): Promise<ISerializedInfo[]>;
+/**
+ * This API finds memory leaks by analyzing specified heap snapshots.
+ * This is equivalent to `memlab find-leaks` with
+ * the `--baseline`, `--target`, and `--final` flags in CLI.
+ *
+ * @param baselineSnapshot the file path of the baseline heap snapshot
+ * @param targetSnapshot the file path of the target heap snapshot
+ * @param finalSnapshot the file path of the final heap snapshot
+ * @param options optionally, you can specify a working
+ * directory (other than the default one) for heap analysis
+ * @returns leak traces detected and clustered from the browser interaction
+ */
+export declare function findLeaksBySnapshotFilePaths(baselineSnapshot: string, targetSnapshot: string, finalSnapshot: string, options?: {
+    workDir?: string;
+}): Promise<ISerializedInfo[]>;
 /**
  * This API analyzes heap snapshot(s) with a specified heap analysis.
  * This is equivalent to `memlab analyze` in CLI.
@@ -181,7 +201,7 @@ export declare function findLeaks(runResult: BrowserInteractionResultReader): Pr
  * })();
  * ```
  */
-export declare function analyze(runResult: BrowserInteractionResultReader, heapAnalyzer: BaseAnalysis, args?: ParsedArgs): Promise<void>;
+export declare function analyze(runResult: BaseResultReader, heapAnalyzer: BaseAnalysis, args?: ParsedArgs): Promise<void>;
 /**
  * This warms up web server by sending web requests to the web sever.
  * This is equivalent to running `memlab warmup` in CLI.

package/dist/API.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"API.d.ts","sourceRoot":"","sources":["../src/API.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,SAAS,EAGT,QAAQ,EACT,MAAM,cAAc,CAAC;AAEtB,OAAO,EAML,YAAY,EAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,WAAW,EAGZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAEnD,OAAO,8BAA8B,MAAM,gDAAgD,CAAC;AAC5F,OAAO,gBAAgB,MAAM,kCAAkC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,WAAW,CAAC;IACzC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;OAEG;IACH,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;OAEG;IACH,SAAS,EAAE,8BAA8B,CAAC;CAC3C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IAGvB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,0BAA0B,CAAC,EAAE,WAAW,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,8BAA8B,CAAC,CAWzC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,GAAG,CAAC,UAAU,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAazE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,8BAA8B,CAAC,CAQzC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,gBAAgB,GAC1B,OAAO,CAAC,eAAe,EAAE,CAAC,CAK5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,4BAA4B,CAChD,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAM,GAC/B,OAAO,CAAC,eAAe,EAAE,CAAC,CAU5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,YAAY,EAC1B,IAAI,GAAE,UAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpE;AAmED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD3E"}

package/dist/API.js

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.testInBrowser = exports.warmup = exports.analyze = exports.findLeaks = exports.takeSnapshots = exports.run = exports.warmupAndTakeSnapshots = void 0;
+exports.testInBrowser = exports.warmup = exports.analyze = exports.findLeaksBySnapshotFilePaths = exports.findLeaks = exports.takeSnapshots = exports.run = exports.warmupAndTakeSnapshots = void 0;
 const core_1 = require("@memlab/core");
 const e2e_1 = require("@memlab/e2e");
 const APIUtils_1 = __importDefault(require("./lib/APIUtils"));
@@ -52,7 +52,9 @@ function warmupAndTakeSnapshots(options = {}) {
         config.scenario = options.scenario;
         const testPlanner = new e2e_1.TestPlanner({ config });
         const { evalInBrowserAfterInitLoad } = options;
-        yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
+        if (!options.skipWarmup) {
+            yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
+        }
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
         return BrowserInteractionResultReader_1.default.from(config.workDir);
     });
@@ -86,7 +88,9 @@ function run(runOptions = {}) {
         config.scenario = runOptions.scenario;
         const testPlanner = new e2e_1.TestPlanner({ config });
         const { evalInBrowserAfterInitLoad } = runOptions;
-        yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
+        if (!runOptions.skipWarmup) {
+            yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
+        }
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
         const runResult = BrowserInteractionResultReader_1.default.from(config.workDir);
         const leaks = yield findLeaks(runResult);
@@ -125,7 +129,7 @@ function takeSnapshots(options = {}) {
 }
 exports.takeSnapshots = takeSnapshots;
 /**
- * This API finds memory leaks by analyzing heap snapshot(s)
+ * This API finds memory leaks by analyzing heap snapshot(s).
  * This is equivalent to `memlab find-leaks` in CLI.
  *
  * @param runResult return value of a browser interaction run
@@ -152,6 +156,32 @@ function findLeaks(runResult) {
     });
 }
 exports.findLeaks = findLeaks;
+/**
+ * This API finds memory leaks by analyzing specified heap snapshots.
+ * This is equivalent to `memlab find-leaks` with
+ * the `--baseline`, `--target`, and `--final` flags in CLI.
+ *
+ * @param baselineSnapshot the file path of the baseline heap snapshot
+ * @param targetSnapshot the file path of the target heap snapshot
+ * @param finalSnapshot the file path of the final heap snapshot
+ * @param options optionally, you can specify a working
+ * directory (other than the default one) for heap analysis
+ * @returns leak traces detected and clustered from the browser interaction
+ */
+function findLeaksBySnapshotFilePaths(baselineSnapshot, targetSnapshot, finalSnapshot, options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        core_1.config.useExternalSnapshot = true;
+        core_1.config.externalSnapshotFilePaths = [
+            baselineSnapshot,
+            targetSnapshot,
+            finalSnapshot,
+        ];
+        core_1.fileManager.initDirs(core_1.config, { workDir: options.workDir });
+        core_1.config.chaseWeakMapEdge = false;
+        return yield core_1.analysis.checkLeak();
+    });
+}
+exports.findLeaksBySnapshotFilePaths = findLeaksBySnapshotFilePaths;
 /**
  * This API analyzes heap snapshot(s) with a specified heap analysis.
  * This is equivalent to `memlab analyze` in CLI.
@@ -309,30 +339,37 @@ function testInBrowser(options = {}) {
         const testPlanner = (_b = options.testPlanner) !== null && _b !== void 0 ? _b : e2e_1.defaultTestPlanner;
         let interactionManager = null;
         let xvfb = null;
+        let browser = null;
+        let page = null;
+        let maybeError = null;
         try {
             xvfb = e2e_1.Xvfb.startIfEnabled();
-            const browser = yield APIUtils_1.default.getBrowser();
+            browser = yield APIUtils_1.default.getBrowser();
             const pages = yield browser.pages();
-            const page = pages.length > 0 ? pages[0] : yield browser.newPage();
+            page = pages.length > 0 ? pages[0] : yield browser.newPage();
+            // create and configure web page interaction manager
             interactionManager = new e2e_1.E2EInteractionManager(page, browser);
             if (options.evalInBrowserAfterInitLoad) {
                 interactionManager.setEvalFuncAfterInitLoad(options.evalInBrowserAfterInitLoad);
             }
             const visitPlan = testPlanner.getVisitPlan();
+            // setup page configuration
             config.setDevice(visitPlan.device);
             autoDismissDialog(page);
             yield initBrowserInfoInConfig(browser);
             core_1.browserInfo.monitorWebConsole(page);
             yield setupPage(page, options);
+            // interact with the web page and take heap snapshots
             yield interactionManager.visitAndGetSnapshots(options);
-            yield core_1.utils.closePuppeteer(browser, [page]);
         }
         catch (ex) {
-            const error = core_1.utils.getError(ex);
-            core_1.utils.checkUninstalledLibrary(error);
-            core_1.info.error(error.message);
+            maybeError = core_1.utils.getError(ex);
+            core_1.utils.checkUninstalledLibrary(maybeError);
         }
         finally {
+            if (browser && page) {
+                yield core_1.utils.closePuppeteer(browser, [page]);
+            }
             if (interactionManager) {
                 interactionManager.clearCDPSession();
             }
@@ -343,6 +380,9 @@ function testInBrowser(options = {}) {
                     }
                 });
             }
+            if (maybeError != null) {
+                core_1.utils.haltOrThrow(maybeError);
+            }
         }
     });
 }

package/dist/__tests__/API/E2EBasicAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EBasicAnalysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EBasicAnalysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EDetachedDOMAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EDetachedDOMAnalysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EDetachedDOMAnalysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EDuplicateObjectAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EDuplicateObjectAnalysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EDuplicateObjectAnalysis.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/API/E2EFindLeaks.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EFindLeaks.example.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EFindLeaks.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EFindMemoryLeaks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EFindMemoryLeaks.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EFindMemoryLeaks.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EFindMemoryLeaksWithSnapshotFiles.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall web_perf_infra
+ */
+export {};
+//# sourceMappingURL=E2EFindMemoryLeaksWithSnapshotFiles.test.d.ts.map

package/dist/__tests__/API/E2EFindMemoryLeaksWithSnapshotFiles.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EFindMemoryLeaksWithSnapshotFiles.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EFindMemoryLeaksWithSnapshotFiles.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EFindMemoryLeaksWithSnapshotFiles.test.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall web_perf_infra
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const index_1 = require("../../index");
+const E2ETestSettings_1 = require("./lib/E2ETestSettings");
+beforeEach(E2ETestSettings_1.testSetup);
+function injectDetachedDOMElements() {
+    // @ts-ignore
+    window.injectHookForLink4 = () => {
+        class TestObject {
+        }
+        const arr = [];
+        for (let i = 0; i < 23; ++i) {
+            arr.push(document.createElement('div'));
+        }
+        // @ts-ignore
+        window.__injectedValue = arr;
+        // @ts-ignore
+        window._path_1 = { x: { y: document.createElement('div') } };
+        // @ts-ignore
+        window._path_2 = new Set([document.createElement('div')]);
+        // @ts-ignore
+        window._randomObject = [new TestObject()];
+    };
+}
+test('leak detector can find detached DOM elements', () => __awaiter(void 0, void 0, void 0, function* () {
+    const result = yield (0, index_1.takeSnapshots)({
+        scenario: E2ETestSettings_1.scenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+    });
+    // copy heap snapshots to a different location
+    const snapshotFiles = result.getSnapshotFiles();
+    const tmpDir = core_1.fileManager.generateTmpHeapDir();
+    const newSnapshotFiles = [];
+    snapshotFiles.forEach(file => {
+        const newFile = path_1.default.join(tmpDir, path_1.default.basename(file));
+        newSnapshotFiles.push(newFile);
+        fs_extra_1.default.moveSync(file, newFile);
+    });
+    fs_extra_1.default.rmdirSync(result.getRootDirectory(), { recursive: true });
+    // find memory leaks with the new snapshot files
+    const leaks = yield (0, index_1.findLeaksBySnapshotFilePaths)(newSnapshotFiles[0], newSnapshotFiles[1], newSnapshotFiles[2]);
+    // detected all different leak trace cluster
+    expect(leaks.length >= 1).toBe(true);
+    // expect all traces are found
+    expect(leaks.some(leak => JSON.stringify(leak).includes('__injectedValue')));
+    expect(leaks.some(leak => JSON.stringify(leak).includes('_path_1')));
+    expect(leaks.some(leak => JSON.stringify(leak).includes('_path_2')));
+    // finally clean up the temporary directory
+    fs_extra_1.default.rmdirSync(tmpDir, { recursive: true });
+}), E2ETestSettings_1.testTimeout);
+test('takeSnapshot API allows to throw and catch exceptions from scenario', () => __awaiter(void 0, void 0, void 0, function* () {
+    const scenarioThatThrows = Object.assign({}, E2ETestSettings_1.scenario);
+    const errorMessage = 'throw from scenario.action';
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    scenarioThatThrows.action = (_page) => __awaiter(void 0, void 0, void 0, function* () {
+        throw new Error(errorMessage);
+    });
+    expect.assertions(1);
+    yield expect((0, index_1.takeSnapshots)({
+        scenario: scenarioThatThrows,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+    })).rejects.toThrow(errorMessage);
+}), E2ETestSettings_1.testTimeout);
+test('run API allows to throw and catch exceptions from scenario', () => __awaiter(void 0, void 0, void 0, function* () {
+    const scenarioThatThrows = Object.assign({}, E2ETestSettings_1.scenario);
+    const errorMessage = 'throw from scenario.action';
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    scenarioThatThrows.action = (_page) => __awaiter(void 0, void 0, void 0, function* () {
+        throw new Error(errorMessage);
+    });
+    expect.assertions(1);
+    yield expect((0, index_1.run)({
+        scenario: scenarioThatThrows,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+    })).rejects.toThrow(errorMessage);
+}), E2ETestSettings_1.testTimeout);

package/dist/__tests__/API/E2EInjectLeaksWithSetup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EInjectLeaksWithSetup.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EInjectLeaksWithSetup.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EReloadInSetup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EReloadInSetup.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EReloadInSetup.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EResultReader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EResultReader.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EResultReader.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EResultReader.test.js

@@ -26,6 +26,7 @@ const fs_1 = __importDefault(require("fs"));
 const BrowserInteractionResultReader_1 = __importDefault(require("../../result-reader/BrowserInteractionResultReader"));
 const index_1 = require("../../index");
 const E2ETestSettings_1 = require("./lib/E2ETestSettings");
+const SnapshotResultReader_1 = __importDefault(require("../../result-reader/SnapshotResultReader"));
 beforeEach(E2ETestSettings_1.testSetup);
 function inject() {
     // @ts-ignore
@@ -70,3 +71,38 @@ test('ResultReader.from is working as expected', () => __awaiter(void 0, void 0,
     });
     checkResultReader(BrowserInteractionResultReader_1.default.from(result.getRootDirectory()));
 }), E2ETestSettings_1.testTimeout);
+function injectDetachedDOMElements() {
+    // @ts-ignore
+    window.injectHookForLink4 = () => {
+        class TestObject {
+        }
+        const arr = [];
+        for (let i = 0; i < 23; ++i) {
+            arr.push(document.createElement('div'));
+        }
+        // @ts-ignore
+        window.__injectedValue = arr;
+        // @ts-ignore
+        window._path_1 = { x: { y: document.createElement('div') } };
+        // @ts-ignore
+        window._path_2 = new Set([document.createElement('div')]);
+        // @ts-ignore
+        window._randomObject = [new TestObject()];
+    };
+}
+test('SnapshotResultReader is working as expected', () => __awaiter(void 0, void 0, void 0, function* () {
+    const result = yield (0, index_1.warmupAndTakeSnapshots)({
+        scenario: E2ETestSettings_1.scenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+    });
+    const snapshotFiles = result.getSnapshotFiles();
+    expect(snapshotFiles.length).toBe(3);
+    const reader = SnapshotResultReader_1.default.fromSnapshots(snapshotFiles[0], snapshotFiles[1], snapshotFiles[2]);
+    const leaks = yield (0, index_1.findLeaks)(reader);
+    // detected all different leak trace cluster
+    expect(leaks.length >= 1).toBe(true);
+    // expect all traces are found
+    expect(leaks.some(leak => JSON.stringify(leak).includes('__injectedValue')));
+    expect(leaks.some(leak => JSON.stringify(leak).includes('_path_1')));
+    expect(leaks.some(leak => JSON.stringify(leak).includes('_path_2')));
+}), E2ETestSettings_1.testTimeout);

package/dist/__tests__/API/E2ERunMultipleSnapshots.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2ERunMultipleSnapshots.example.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2ERunMultipleSnapshots.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2ERunSingleSnapshot.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2ERunSingleSnapshot.example.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2ERunSingleSnapshot.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EShapeUnboundGrowthAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EShapeUnboundGrowthAnalysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EShapeUnboundGrowthAnalysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2EStringAnalysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EStringAnalysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2EStringAnalysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/{E2EFindWebWorkerLeaks.test.d.ts → E2ETestScenarioCallback.test.d.ts}

@@ -8,4 +8,4 @@
  * @oncall web_perf_infra
  */
 export {};
-//# sourceMappingURL=E2EFindWebWorkerLeaks.test.d.ts.map
+//# sourceMappingURL=E2ETestScenarioCallback.test.d.ts.map

package/dist/__tests__/API/E2ETestScenarioCallback.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2ETestScenarioCallback.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/API/E2ETestScenarioCallback.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/API/E2ETestScenarioCallback.test.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall web_perf_infra
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../../index");
+const E2ETestSettings_1 = require("./lib/E2ETestSettings");
+beforeEach(E2ETestSettings_1.testSetup);
+function injectDetachedDOMElements() {
+    // @ts-ignore
+    window.injectHookForLink4 = () => {
+        class TestObject {
+        }
+        const arr = [];
+        for (let i = 0; i < 23; ++i) {
+            arr.push(document.createElement('div'));
+        }
+        // @ts-ignore
+        window.__injectedValue = arr;
+        // @ts-ignore
+        window._path_1 = { x: { y: document.createElement('div') } };
+        // @ts-ignore
+        window._path_2 = new Set([document.createElement('div')]);
+        // @ts-ignore
+        window._randomObject = [new TestObject()];
+    };
+}
+test('callbacks in test scenarios are called in the right order', () => __awaiter(void 0, void 0, void 0, function* () {
+    const actualCalls = [];
+    // define a test scenario with all callbacks offered by memlab
+    const selfDefinedScenario = {
+        app: () => {
+            actualCalls.push('app');
+            return 'test-spa';
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        beforeInitialPageLoad: (_page) => __awaiter(void 0, void 0, void 0, function* () {
+            actualCalls.push('beforeInitialPageLoad');
+        }),
+        cookies: () => {
+            actualCalls.push('cookies');
+            return [];
+        },
+        repeat: () => {
+            actualCalls.push('repeat');
+            return 0;
+        },
+        isPageLoaded: (page) => __awaiter(void 0, void 0, void 0, function* () {
+            actualCalls.push('isPageLoaded');
+            yield page.waitForNavigation({
+                // consider navigation to be finished when there are
+                // no more than 2 network connections for at least 500 ms.
+                waitUntil: 'networkidle2',
+                // Maximum navigation time in milliseconds
+                timeout: 5000,
+            });
+            return true;
+        }),
+        url: () => {
+            actualCalls.push('url');
+            return '';
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        setup: (_page) => __awaiter(void 0, void 0, void 0, function* () {
+            actualCalls.push('setup');
+        }),
+        action: (page) => __awaiter(void 0, void 0, void 0, function* () {
+            actualCalls.push('action');
+            yield page.click('[data-testid="link-4"]');
+        }),
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        back: (_page) => __awaiter(void 0, void 0, void 0, function* () {
+            actualCalls.push('back');
+        }),
+        beforeLeakFilter: (
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        _snapshot, 
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        _leakedNodeIds) => {
+            actualCalls.push('beforeLeakFilter');
+        },
+        leakFilter: (node) => {
+            actualCalls.push('leakFilter');
+            return node.name === 'TestObject' && node.type === 'object';
+        },
+    };
+    // run test scenario
+    yield (0, index_1.run)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+        skipWarmup: true,
+    });
+    // squash all leakFilter call into a single identifier
+    let normalizedCalls = squash(actualCalls, ['leakFilter', 'isPageLoaded']);
+    normalizedCalls = normalizedCalls.slice(normalizedCalls.lastIndexOf('url'));
+    // expect all callbacks are called in the right order
+    expect(normalizedCalls).toEqual([
+        // the first 4 calls (app, cookies, repeat, url) can be in any order
+        'url',
+        'repeat',
+        'app',
+        'cookies',
+        // the following calls must be in the exact order listed
+        'beforeInitialPageLoad',
+        'isPageLoaded',
+        'setup',
+        'action',
+        'isPageLoaded',
+        'back',
+        'isPageLoaded',
+        'beforeLeakFilter',
+        'leakFilter',
+    ]);
+}), E2ETestSettings_1.testTimeout);
+// Squashes consecutive occurrences of a specified element in
+// an array into a single occurrence of that element
+function squash(arr, elementsToSquash) {
+    const squashSet = new Set(elementsToSquash);
+    return arr.filter((value, index) => !squashSet.has(value) || value !== arr[index - 1]);
+}

package/dist/__tests__/API/lib/E2ETestSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2ETestSettings.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/API/lib/E2ETestSettings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAGpC,eAAO,MAAM,WAAW,QAAgB,CAAC;AAEzC,eAAO,MAAM,mBAAmB;;;;CAAkB,CAAC;AAEnD,eAAO,MAAM,QAAQ;eACV,MAAM;eACN,MAAM;mBACM,IAAI,KAAG,QAAQ,IAAI,CAAC;CAE1C,CAAC;AAEF,eAAO,MAAM,SAAS,QAAO,IAK5B,CAAC;AAGF,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/__tests__/heap/E2EHeapParser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"E2EHeapParser.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/heap/E2EHeapParser.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,QAAQ,EAA2B,MAAM,cAAc,CAAC;AAKrE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,EAAE,QAAQ,CAAC;KACpB;CACF"}

package/dist/__tests__/heap/examples/example-1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-1.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-1.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-2.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-2.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-3.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-3.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-4.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-4.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-5.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-5.test.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-5.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-6.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-6.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-6.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/examples/example-7.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-7.test.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/examples/example-7.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__tests__/heap/lib/HeapParserTestUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapParserTestUtils.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/heap/lib/HeapParserTestUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAUhD,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,IAAI,EACxB,eAAe,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,GACpD,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/__tests__/heap/lib/HeapParserTestUtils.js

@@ -69,6 +69,7 @@ function saveSnapshotToFile(page, file) {
 const TEST_URL = 'about:blank';
 function dumpHeap(snapshotFile, leakInjector) {
     return __awaiter(this, void 0, void 0, function* () {
+        core_1.utils.tryToMutePuppeteerWarning();
         const browser = yield puppeteer.launch(core_1.config.puppeteerConfig);
         const page = yield browser.newPage();
         // set page size

package/dist/__tests__/packages/heap-analysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-analysis.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/packages/heap-analysis.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export declare function registerPackage(): Promise<void>;
 export * from './API';
 export * from '@memlab/heap-analysis';
 export { default as BrowserInteractionResultReader } from './result-reader/BrowserInteractionResultReader';
+export { default as SnapshotResultReader } from './result-reader/SnapshotResultReader';
 export { dumpNodeHeapSnapshot, getNodeInnocentHeap, takeNodeMinimalHeap, } from '@memlab/core';
 /** @internal */
 export { config } from '@memlab/core';

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,gBAAgB;AAChB,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAErD;AAED,cAAc,OAAO,CAAC;AACtB,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAC,OAAO,IAAI,8BAA8B,EAAC,MAAM,gDAAgD,CAAC;AACzG,OAAO,EAAC,OAAO,IAAI,oBAAoB,EAAC,MAAM,sCAAsC,CAAC;AACrF,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,gBAAgB;AAChB,OAAO,EAAC,MAAM,EAAC,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = exports.takeNodeMinimalHeap = exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.BrowserInteractionResultReader = exports.registerPackage = void 0;
+exports.config = exports.takeNodeMinimalHeap = exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.SnapshotResultReader = exports.BrowserInteractionResultReader = exports.registerPackage = void 0;
 const path_1 = __importDefault(require("path"));
 const core_1 = require("@memlab/core");
 /** @internal */
@@ -49,6 +49,8 @@ __exportStar(require("./API"), exports);
 __exportStar(require("@memlab/heap-analysis"), exports);
 var BrowserInteractionResultReader_1 = require("./result-reader/BrowserInteractionResultReader");
 Object.defineProperty(exports, "BrowserInteractionResultReader", { enumerable: true, get: function () { return __importDefault(BrowserInteractionResultReader_1).default; } });
+var SnapshotResultReader_1 = require("./result-reader/SnapshotResultReader");
+Object.defineProperty(exports, "SnapshotResultReader", { enumerable: true, get: function () { return __importDefault(SnapshotResultReader_1).default; } });
 var core_2 = require("@memlab/core");
 Object.defineProperty(exports, "dumpNodeHeapSnapshot", { enumerable: true, get: function () { return core_2.dumpNodeHeapSnapshot; } });
 Object.defineProperty(exports, "getNodeInnocentHeap", { enumerable: true, get: function () { return core_2.getNodeInnocentHeap; } });

package/dist/lib/APIUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"APIUtils.d.ts","sourceRoot":"","sources":["../../src/lib/APIUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,cAAc,CAAC;AAU/C,iBAAe,UAAU,CACvB,OAAO,GAAE;IAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAM,GACtD,OAAO,CAAC,OAAO,CAAC,CAoBlB;;;;AAED,wBAEE"}

package/dist/lib/APIUtils.js

@@ -29,6 +29,7 @@ function getBrowser(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const runConfig = (_a = options.config) !== null && _a !== void 0 ? _a : core_1.config;
         let browser;
+        core_1.utils.tryToMutePuppeteerWarning();
         if (runConfig.isLocalPuppeteer && !options.warmup) {
             try {
                 browser = yield puppeteer.connect(Object.assign({ browserURL: `http://localhost:${runConfig.localBrowserPort}` }, runConfig.puppeteerConfig));

package/dist/result-reader/BaseResultReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseResultReader.d.ts","sourceRoot":"","sources":["../../src/result-reader/BaseResultReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAQ,WAAW,EAAC,MAAM,cAAc,CAAC;AAGhD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAgB;IACnC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;IACnC,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;OAIG;IACH,SAAS,aAAa,OAAO,SAAK;IASlC,SAAS,CAAC,KAAK,IAAI,IAAI;IAOvB;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,SAAK,GAAG,gBAAgB;IAI3C;;;;;;;;;;;;;;;;;OAiBG;IACI,gBAAgB,IAAI,MAAM;IAKjC;;;;;;;;;;;;;;;OAeG;IACI,OAAO,IAAI,IAAI;CAOvB"}

package/dist/result-reader/BrowserInteractionResultReader.d.ts

@@ -12,7 +12,7 @@ import BaseResultReader from './BaseResultReader';
 /**
  * A utility entity to read all generated files from
  * the directory holding the data and results from the
- * last browser interaction run
+ * last MemLab browser interaction run
  */
 export default class BrowserInteractionResultReader extends BaseResultReader {
     /**

package/dist/result-reader/BrowserInteractionResultReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserInteractionResultReader.d.ts","sourceRoot":"","sources":["../../src/result-reader/BrowserInteractionResultReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAE,WAAW,EAAC,MAAM,cAAc,CAAC;AAK3D,OAAO,gBAAgB,MAAM,oBAAoB,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,8BAA+B,SAAQ,gBAAgB;IAC1E;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,SAAK,GAAG,8BAA8B;IAIzD;;;;;;;;;;;;;;;OAeG;IACI,gBAAgB,IAAI,MAAM,EAAE;IASnC;;;;;;;;;;;;;;;OAeG;IACI,kBAAkB,IAAI,MAAM;IAKnC;;;;;;;;;;;;;;;;OAgBG;IACI,mBAAmB,IAAI,WAAW,EAAE;IAQ3C;;;;;;;;;;;;;;;;OAgBG;IACI,cAAc,IAAI,WAAW;CAMrC"}

package/dist/result-reader/BrowserInteractionResultReader.js

@@ -19,7 +19,7 @@ const BaseResultReader_1 = __importDefault(require("./BaseResultReader"));
 /**
  * A utility entity to read all generated files from
  * the directory holding the data and results from the
- * last browser interaction run
+ * last MemLab browser interaction run
  */
 class BrowserInteractionResultReader extends BaseResultReader_1.default {
     /**

package/dist/result-reader/SnapshotResultReader.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall web_perf_infra
+ */
+import { E2EStepInfo, RunMetaInfo } from '@memlab/core';
+import BaseResultReader from './BaseResultReader';
+/**
+ * A utility entity to read all MemLab files generated from
+ * baseline, target and final heap snapshots.
+ *
+ * The most useful feature of this class is when you have
+ * three separate snapshots (baseline, target, and final)
+ * that are not taken from MemLab, but you still would
+ * like to use the `findLeaks` to detect memory leaks:
+ *
+ * ```javascript
+ * const {SnapshotResultReader, findLeaks} = require('@memlab/api');
+ *
+ * // baseline, target, and final are file paths of heap snapshot files
+ * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+ * const leaks = await findLeaks(reader);
+ * ```
+ */
+export default class SnapshotResultReader extends BaseResultReader {
+    private baselineSnapshot;
+    private targetSnapshot;
+    private finalSnapshot;
+    /**
+     * build a result reader
+     * @param workDir absolute path of the directory where the data
+     * and generated files of the memlab run were stored
+     */
+    protected constructor(baselineSnapshot: string, targetSnapshot: string, finalSnapshot: string);
+    private createMetaFilesOnDisk;
+    private checkSnapshotFiles;
+    /**
+     * Build a result reader from baseline, target, and final heap snapshot files.
+     * The three snapshot files do not have to be in the same directory.
+     * @param baselineSnapshot file path of the baseline heap snapshot
+     * @param targetSnapshot file path of the target heap snapshot
+     * @param finalSnapshot file path of the final heap snapshot
+     * @returns the ResultReader instance
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader, findLeaks} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const leaks = await findLeaks(reader);
+     * ```
+     */
+    static fromSnapshots(baselineSnapshot: string, targetSnapshot: string, finalSnapshot: string): SnapshotResultReader;
+    /**
+     * @internal
+     */
+    static from(workDir?: string): BaseResultReader;
+    /**
+     * get all snapshot files related to this SnapshotResultReader
+     * @returns an array of snapshot file's absolute path
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const paths = reader.getSnapshotFiles();
+     * ```
+     */
+    getSnapshotFiles(): string[];
+    /**
+     * @internal
+     */
+    getSnapshotFileDir(): string;
+    /**
+     * browser interaction step sequence
+     * @returns an array of browser interaction step information
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const paths = reader.getInteractionSteps();
+     * ```
+     */
+    getInteractionSteps(): E2EStepInfo[];
+    /**
+     * @internal
+     * general meta data of the browser interaction run
+     * @returns meta data about the entire browser interaction
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const metaInfo = reader.getRunMetaInfo();
+     * ```
+     */
+    getRunMetaInfo(): RunMetaInfo;
+    /**
+     * @internal
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=SnapshotResultReader.d.ts.map

package/dist/result-reader/SnapshotResultReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotResultReader.d.ts","sourceRoot":"","sources":["../../src/result-reader/SnapshotResultReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAS,WAAW,EAAE,WAAW,EAAC,MAAM,cAAc,CAAC;AAI9D,OAAO,gBAAgB,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,OAAO,oBAAqB,SAAQ,gBAAgB;IAChE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;OAIG;IACH,SAAS,aACP,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM;IAavB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,aAAa,CAClB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,oBAAoB;IAQvB;;OAEG;WACW,IAAI,CAAC,OAAO,SAAK,GAAG,gBAAgB;IAKlD;;;;;;;;;;;;OAYG;IACI,gBAAgB,IAAI,MAAM,EAAE;IAInC;;OAEG;IACI,kBAAkB,IAAI,MAAM;IAOnC;;;;;;;;;;;;OAYG;IACI,mBAAmB,IAAI,WAAW,EAAE;IAQ3C;;;;;;;;;;;;;OAaG;IACI,cAAc,IAAI,WAAW;IAIpC;;OAEG;IACI,OAAO,IAAI,IAAI;CAGvB"}

package/dist/result-reader/SnapshotResultReader.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall web_perf_infra
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const core_2 = require("@memlab/core");
+const BaseResultReader_1 = __importDefault(require("./BaseResultReader"));
+/**
+ * A utility entity to read all MemLab files generated from
+ * baseline, target and final heap snapshots.
+ *
+ * The most useful feature of this class is when you have
+ * three separate snapshots (baseline, target, and final)
+ * that are not taken from MemLab, but you still would
+ * like to use the `findLeaks` to detect memory leaks:
+ *
+ * ```javascript
+ * const {SnapshotResultReader, findLeaks} = require('@memlab/api');
+ *
+ * // baseline, target, and final are file paths of heap snapshot files
+ * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+ * const leaks = await findLeaks(reader);
+ * ```
+ */
+class SnapshotResultReader extends BaseResultReader_1.default {
+    /**
+     * build a result reader
+     * @param workDir absolute path of the directory where the data
+     * and generated files of the memlab run were stored
+     */
+    constructor(baselineSnapshot, targetSnapshot, finalSnapshot) {
+        const fileManager = new core_2.FileManager();
+        const workDir = fileManager.generateTmpHeapDir();
+        fs_extra_1.default.ensureDirSync(workDir);
+        super(workDir);
+        this.baselineSnapshot = baselineSnapshot;
+        this.targetSnapshot = targetSnapshot;
+        this.finalSnapshot = finalSnapshot;
+        this.checkSnapshotFiles();
+        this.createMetaFilesOnDisk(fileManager, workDir);
+    }
+    createMetaFilesOnDisk(fileManager, workDir) {
+        fileManager.initDirs(core_1.config, { workDir });
+        const visitOrder = this.getInteractionSteps();
+        const snapSeqFile = fileManager.getSnapshotSequenceMetaFile({ workDir });
+        fs_extra_1.default.writeFileSync(snapSeqFile, JSON.stringify(visitOrder, null, 2), 'UTF-8');
+    }
+    checkSnapshotFiles() {
+        if (!fs_extra_1.default.existsSync(this.baselineSnapshot) ||
+            !fs_extra_1.default.existsSync(this.targetSnapshot) ||
+            !fs_extra_1.default.existsSync(this.finalSnapshot)) {
+            throw core_2.utils.haltOrThrow('invalid file path of baseline, target, or final heap snapshots');
+        }
+    }
+    /**
+     * Build a result reader from baseline, target, and final heap snapshot files.
+     * The three snapshot files do not have to be in the same directory.
+     * @param baselineSnapshot file path of the baseline heap snapshot
+     * @param targetSnapshot file path of the target heap snapshot
+     * @param finalSnapshot file path of the final heap snapshot
+     * @returns the ResultReader instance
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader, findLeaks} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const leaks = await findLeaks(reader);
+     * ```
+     */
+    static fromSnapshots(baselineSnapshot, targetSnapshot, finalSnapshot) {
+        return new SnapshotResultReader(baselineSnapshot, targetSnapshot, finalSnapshot);
+    }
+    /**
+     * @internal
+     */
+    static from(workDir = '') {
+        throw core_2.utils.haltOrThrow('SnapshotResultReader.from is not supported');
+        return new BaseResultReader_1.default(workDir);
+    }
+    /**
+     * get all snapshot files related to this SnapshotResultReader
+     * @returns an array of snapshot file's absolute path
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const paths = reader.getSnapshotFiles();
+     * ```
+     */
+    getSnapshotFiles() {
+        return [this.baselineSnapshot, this.targetSnapshot, this.finalSnapshot];
+    }
+    /**
+     * @internal
+     */
+    getSnapshotFileDir() {
+        throw core_2.utils.haltOrThrow('SnapshotResultReader getSnapshotFileDir() method is not supported');
+        return '';
+    }
+    /**
+     * browser interaction step sequence
+     * @returns an array of browser interaction step information
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const paths = reader.getInteractionSteps();
+     * ```
+     */
+    getInteractionSteps() {
+        return this.fileManager.createVisitOrderWithSnapshots(this.baselineSnapshot, this.targetSnapshot, this.finalSnapshot);
+    }
+    /**
+     * @internal
+     * general meta data of the browser interaction run
+     * @returns meta data about the entire browser interaction
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {SnapshotResultReader} = require('@memlab/api');
+     *
+     * // baseline, target, and final are file paths of heap snapshot files
+     * const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
+     * const metaInfo = reader.getRunMetaInfo();
+     * ```
+     */
+    getRunMetaInfo() {
+        return new core_2.RunMetaInfoManager().loadRunMetaExternalTemplate();
+    }
+    /**
+     * @internal
+     */
+    cleanup() {
+        // do nothing
+    }
+}
+exports.default = SnapshotResultReader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/api",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "license": "MIT",
   "description": "memlab API",
   "author": "Liang Gong <lgong@fb.com>",
@@ -35,7 +35,8 @@
     "chalk": "^4.0.0",
     "fs-extra": "^4.0.2",
     "minimist": "^1.2.0",
-    "puppeteer": "^13.5.1",
+    "puppeteer": "^21.0.3",
+    "puppeteer-core": "^21.0.3",
     "string-width": "^4.2.0",
     "util.promisify": "^1.1.1",
     "xvfb": "^0.4.0"
@@ -46,8 +47,8 @@
     "@types/minimist": "^1.2.2",
     "@types/node": "^12.16.3",
     "@types/puppeteer": "^5.4.4",
-    "jest": "^27.5.1",
-    "ts-jest": "^27.1.4",
+    "jest": "^29.6.2",
+    "ts-jest": "^29.1.1",
     "typescript": "^4.6.3"
   },
   "repository": {

package/dist/__tests__/API/E2EFindWebWorkerLeaks.test.js

@@ -1,69 +0,0 @@
-"use strict";
-/**
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- * @format
- * @oncall web_perf_infra
- */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const index_1 = require("../../index");
-const E2ETestSettings_1 = require("./lib/E2ETestSettings");
-beforeEach(E2ETestSettings_1.testSetup);
-test('self-defined leak detector can find Web Worker TestObject (in initial load)', () => __awaiter(void 0, void 0, void 0, function* () {
-    const selfDefinedScenario = {
-        app: () => 'test-spa',
-        url: () => '',
-        leakFilter: (node) => {
-            return node.name === 'WorkerTestObject' && node.type === 'object';
-        },
-    };
-    const result = yield (0, index_1.run)({
-        scenario: selfDefinedScenario,
-        webWorker: null,
-    });
-    // detected all different leak trace cluster
-    expect(result.leaks.length).toBe(1);
-}), E2ETestSettings_1.testTimeout);
-test('self-defined leak detector can find Web Worker TestObject with specified worker name (in initial load)', () => __awaiter(void 0, void 0, void 0, function* () {
-    const selfDefinedScenario = {
-        app: () => 'test-spa',
-        url: () => '',
-        leakFilter: (node) => {
-            return node.name === 'WorkerTestObject' && node.type === 'object';
-        },
-    };
-    const result = yield (0, index_1.run)({
-        scenario: selfDefinedScenario,
-        webWorker: 'test-worker',
-    });
-    // detected all different leak trace cluster
-    expect(result.leaks.length).toBe(1);
-}), E2ETestSettings_1.testTimeout);
-test('self-defined leak detector can find Web Worker TestObject (during interaction)', () => __awaiter(void 0, void 0, void 0, function* () {
-    const selfDefinedScenario = {
-        app: () => 'test-spa',
-        url: () => '',
-        action: (page) => __awaiter(void 0, void 0, void 0, function* () { return yield page.click('[data-testid="link-4"]'); }),
-        leakFilter: (node) => {
-            return node.name === 'WorkerTestObject' && node.type === 'object';
-        },
-    };
-    const result = yield (0, index_1.run)({
-        scenario: selfDefinedScenario,
-        webWorker: null,
-    });
-    // detected all different leak trace cluster
-    expect(result.leaks.length).toBe(1);
-}), E2ETestSettings_1.testTimeout);