@memlab/api 1.0.25 → 1.0.27

package/dist/API.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ParsedArgs } from 'minimist';
 import type { AnyFunction, ISerializedInfo, IScenario, Optional } from '@memlab/core';
+import { ConsoleMode } from './state/ConsoleModeManager';
 import { MemLabConfig } from '@memlab/core';
 import { TestPlanner } from '@memlab/e2e';
 import { BaseAnalysis } from '@memlab/heap-analysis';
@@ -57,6 +58,15 @@ export type RunOptions = {
      * skip warmup page load for the target web app
      */
     skipWarmup?: boolean;
+    /**
+     * specifying the terminal output mode, default is `default`.
+     * For more details. please check out {@link ConsoleMode}
+     */
+    consoleMode?: ConsoleMode;
+    /**
+     * specify the Chromium binary for E2E run
+     */
+    chromiumBinary?: string;
 };
 /**
  * A data structure holding the result of the {@link run} API call.
@@ -122,7 +132,7 @@ export declare function warmupAndTakeSnapshots(options?: RunOptions): Promise<Br
  * })();
  * ```
  */
-export declare function run(runOptions?: RunOptions): Promise<RunResult>;
+export declare function run(options?: RunOptions): Promise<RunResult>;
 /**
  * This API runs E2E interaction and takes heap snapshots.
  * This is equivalent to running `memlab snapshot` in CLI.
@@ -147,6 +157,9 @@ export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInte
  * This is equivalent to `memlab find-leaks` in CLI.
  *
  * @param runResult return value of a browser interaction run
+ * @param options configure memory leak detection run
+ * @param options.consoleMode specify the terminal output
+ * mode (see {@link ConsoleMode})
  * @returns leak traces detected and clustered from the browser interaction
  * * **Examples**:
  * ```javascript
@@ -156,12 +169,14 @@ export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInte
  *   const scenario = {
  *     url: () => 'https://www.facebook.com',
  *   };
- *   const result = await takeSnapshots({scenario});
- *   const leaks = findLeaks(result);
+ *   const result = await takeSnapshots({scenario, consoleMode: 'SILENT'});
+ *   const leaks = findLeaks(result, {consoleMode: 'CONTINUOUS_TEST'});
  * })();
  * ```
  */
-export declare function findLeaks(runResult: BaseResultReader): Promise<ISerializedInfo[]>;
+export declare function findLeaks(runResult: BaseResultReader, options?: {
+    consoleMode?: ConsoleMode;
+}): Promise<ISerializedInfo[]>;
 /**
  * This API finds memory leaks by analyzing specified heap snapshots.
  * This is equivalent to `memlab find-leaks` with
@@ -170,12 +185,16 @@ export declare function findLeaks(runResult: BaseResultReader): Promise<ISeriali
  * @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
+ * @param options optionally, you can specify a mode for heap analysis
+ * @param options.workDir specify a working directory (other than
+ * the default one)
+ * @param options.consoleMode specify the terminal output
+ * mode (see {@link ConsoleMode})
  * @returns leak traces detected and clustered from the browser interaction
  */
 export declare function findLeaksBySnapshotFilePaths(baselineSnapshot: string, targetSnapshot: string, finalSnapshot: string, options?: {
     workDir?: string;
+    consoleMode?: ConsoleMode;
 }): Promise<ISerializedInfo[]>;
 /**
  * This API analyzes heap snapshot(s) with a specified heap analysis.

package/dist/API.d.ts.map

@@ -1 +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;AA4DD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqD3E"}
+{"version":3,"file":"API.d.ts","sourceRoot":"","sources":["../src/API.ts"],"names":[],"mappings":"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"}

package/dist/API.js

@@ -26,6 +26,7 @@ const core_1 = require("@memlab/core");
 const e2e_1 = require("@memlab/e2e");
 const APIUtils_1 = __importDefault(require("./lib/APIUtils"));
 const BrowserInteractionResultReader_1 = __importDefault(require("./result-reader/BrowserInteractionResultReader"));
+const APIStateManager_1 = __importDefault(require("./state/APIStateManager"));
 /**
  * This API warms up web server, runs E2E interaction, and takes heap snapshots.
  * This is equivalent to running `memlab warmup-and-snapshot` in CLI.
@@ -48,15 +49,16 @@ const BrowserInteractionResultReader_1 = __importDefault(require("./result-reade
 function warmupAndTakeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const config = getConfigFromRunOptions(options);
-        config.externalCookiesFile = options.cookiesFile;
-        config.scenario = options.scenario;
+        const state = APIStateManager_1.default.getAndUpdateState(config, options);
         const testPlanner = new e2e_1.TestPlanner({ config });
         const { evalInBrowserAfterInitLoad } = options;
         if (!options.skipWarmup) {
             yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
         }
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
-        return BrowserInteractionResultReader_1.default.from(config.workDir);
+        const ret = BrowserInteractionResultReader_1.default.from(config.workDir);
+        APIStateManager_1.default.restoreState(config, state);
+        return ret;
     });
 }
 exports.warmupAndTakeSnapshots = warmupAndTakeSnapshots;
@@ -81,19 +83,19 @@ exports.warmupAndTakeSnapshots = warmupAndTakeSnapshots;
  * })();
  * ```
  */
-function run(runOptions = {}) {
+function run(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const config = getConfigFromRunOptions(runOptions);
-        config.externalCookiesFile = runOptions.cookiesFile;
-        config.scenario = runOptions.scenario;
+        const config = getConfigFromRunOptions(options);
+        const state = APIStateManager_1.default.getAndUpdateState(config, options);
         const testPlanner = new e2e_1.TestPlanner({ config });
-        const { evalInBrowserAfterInitLoad } = runOptions;
-        if (!runOptions.skipWarmup) {
+        const { evalInBrowserAfterInitLoad } = options;
+        if (!options.skipWarmup) {
             yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
         }
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
         const runResult = BrowserInteractionResultReader_1.default.from(config.workDir);
         const leaks = yield findLeaks(runResult);
+        APIStateManager_1.default.restoreState(config, state);
         return { leaks, runResult };
     });
 }
@@ -119,12 +121,13 @@ exports.run = run;
 function takeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const config = getConfigFromRunOptions(options);
-        config.externalCookiesFile = options.cookiesFile;
-        config.scenario = options.scenario;
+        const state = APIStateManager_1.default.getAndUpdateState(config, options);
         const testPlanner = new e2e_1.TestPlanner();
         const { evalInBrowserAfterInitLoad } = options;
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
-        return BrowserInteractionResultReader_1.default.from(config.workDir);
+        const ret = BrowserInteractionResultReader_1.default.from(config.workDir);
+        APIStateManager_1.default.restoreState(config, state);
+        return ret;
     });
 }
 exports.takeSnapshots = takeSnapshots;
@@ -133,6 +136,9 @@ exports.takeSnapshots = takeSnapshots;
  * This is equivalent to `memlab find-leaks` in CLI.
  *
  * @param runResult return value of a browser interaction run
+ * @param options configure memory leak detection run
+ * @param options.consoleMode specify the terminal output
+ * mode (see {@link ConsoleMode})
  * @returns leak traces detected and clustered from the browser interaction
  * * **Examples**:
  * ```javascript
@@ -142,17 +148,20 @@ exports.takeSnapshots = takeSnapshots;
  *   const scenario = {
  *     url: () => 'https://www.facebook.com',
  *   };
- *   const result = await takeSnapshots({scenario});
- *   const leaks = findLeaks(result);
+ *   const result = await takeSnapshots({scenario, consoleMode: 'SILENT'});
+ *   const leaks = findLeaks(result, {consoleMode: 'CONTINUOUS_TEST'});
  * })();
  * ```
  */
-function findLeaks(runResult) {
+function findLeaks(runResult, options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
+        const state = APIStateManager_1.default.getAndUpdateState(core_1.config, options);
         const workDir = runResult.getRootDirectory();
         core_1.fileManager.initDirs(core_1.config, { workDir });
         core_1.config.chaseWeakMapEdge = false;
-        return yield core_1.analysis.checkLeak();
+        const ret = yield core_1.analysis.checkLeak();
+        APIStateManager_1.default.restoreState(core_1.config, state);
+        return ret;
     });
 }
 exports.findLeaks = findLeaks;
@@ -164,12 +173,16 @@ exports.findLeaks = findLeaks;
  * @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
+ * @param options optionally, you can specify a mode for heap analysis
+ * @param options.workDir specify a working directory (other than
+ * the default one)
+ * @param options.consoleMode specify the terminal output
+ * mode (see {@link ConsoleMode})
  * @returns leak traces detected and clustered from the browser interaction
  */
 function findLeaksBySnapshotFilePaths(baselineSnapshot, targetSnapshot, finalSnapshot, options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
+        const state = APIStateManager_1.default.getAndUpdateState(core_1.config, options);
         core_1.config.useExternalSnapshot = true;
         core_1.config.externalSnapshotFilePaths = [
             baselineSnapshot,
@@ -178,7 +191,9 @@ function findLeaksBySnapshotFilePaths(baselineSnapshot, targetSnapshot, finalSna
         ];
         core_1.fileManager.initDirs(core_1.config, { workDir: options.workDir });
         core_1.config.chaseWeakMapEdge = false;
-        return yield core_1.analysis.checkLeak();
+        const ret = yield core_1.analysis.checkLeak();
+        APIStateManager_1.default.restoreState(core_1.config, state);
+        return ret;
     });
 }
 exports.findLeaksBySnapshotFilePaths = findLeaksBySnapshotFilePaths;
@@ -310,9 +325,9 @@ function initBrowserInfoInConfig(browser, options = {}) {
     var _a;
     return __awaiter(this, void 0, void 0, function* () {
         const config = (_a = options.config) !== null && _a !== void 0 ? _a : core_1.config;
-        core_1.browserInfo.setPuppeteerConfig(config.puppeteerConfig);
+        core_1.browserInfo.recordPuppeteerConfig(config.puppeteerConfig);
         const version = yield browser.version();
-        core_1.browserInfo.setBrowserVersion(version);
+        core_1.browserInfo.recordBrowserVersion(version);
         if (config.verbose) {
             core_1.info.lowLevel(JSON.stringify(core_1.browserInfo, null, 2));
         }

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

@@ -58,29 +58,6 @@ test('leak detector can find detached DOM elements', () => __awaiter(void 0, voi
     expect(leaks.some(leak => JSON.stringify(leak).includes('_path_1')));
     expect(leaks.some(leak => JSON.stringify(leak).includes('_path_2')));
 }), E2ETestSettings_1.testTimeout);
-test('self-defined leak detector can find TestObject', () => __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 === 'TestObject' && node.type === 'object';
-        },
-    };
-    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', `${process.pid}`);
-    fs_extra_1.default.mkdirsSync(workDir);
-    const result = yield (0, index_1.run)({
-        scenario: selfDefinedScenario,
-        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
-        workDir,
-    });
-    // detected all different leak trace cluster
-    expect(result.leaks.length).toBe(1);
-    // expect all traces are found
-    expect(result.leaks.some(leak => JSON.stringify(leak).includes('_randomObject')));
-    const reader = result.runResult;
-    expect(path_1.default.resolve(reader.getRootDirectory())).toBe(path_1.default.resolve(workDir));
-}), E2ETestSettings_1.testTimeout);
 function injectDetachedDOMElementsWithPrompt() {
     // @ts-ignore
     window.injectHookForLink4 = () => {
@@ -121,7 +98,7 @@ test('test runner should work with pages having pop up dialog', () => __awaiter(
             return node.name === 'TestObject' && node.type === 'object';
         },
     };
-    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', `${process.pid}`);
+    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', (0, E2ETestSettings_1.getUniqueID)());
     fs_extra_1.default.mkdirsSync(workDir);
     const result = yield (0, index_1.run)({
         scenario: selfDefinedScenario,

package/dist/__tests__/API/E2EMemoryLeakFilter.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=E2EMemoryLeakFilter.test.d.ts.map

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

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

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

@@ -0,0 +1,121 @@
+"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 os_1 = __importDefault(require("os"));
+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('self-defined leak detector can find TestObject', () => __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 === 'TestObject' && node.type === 'object';
+        },
+    };
+    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', (0, E2ETestSettings_1.getUniqueID)());
+    fs_extra_1.default.mkdirsSync(workDir);
+    const result = yield (0, index_1.run)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+        workDir,
+    });
+    // detected all different leak trace cluster
+    expect(result.leaks.length).toBe(1);
+    // expect all traces are found
+    expect(result.leaks.some(leak => JSON.stringify(leak).includes('_randomObject')));
+    const reader = result.runResult;
+    expect(path_1.default.resolve(reader.getRootDirectory())).toBe(path_1.default.resolve(workDir));
+}), E2ETestSettings_1.testTimeout);
+test('self-defined retainer trace filter work as expected (part 1)', () => __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"]'); }),
+        retainerReferenceFilter: (edge) => {
+            return edge.name_or_index !== '_path_1';
+        },
+    };
+    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', (0, E2ETestSettings_1.getUniqueID)());
+    fs_extra_1.default.mkdirsSync(workDir);
+    const result = yield (0, index_1.run)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+        workDir,
+    });
+    // detected all different leak trace cluster
+    expect(result.leaks.length).toBe(1);
+    // expect the none of the traces to include _path_1
+    expect(result.leaks.every(leak => !JSON.stringify(leak).includes('_path_1')));
+    // expect some of the traces to include _path_2
+    expect(result.leaks.some(leak => JSON.stringify(leak).includes('_path_2')));
+    const reader = result.runResult;
+    expect(path_1.default.resolve(reader.getRootDirectory())).toBe(path_1.default.resolve(workDir));
+}), E2ETestSettings_1.testTimeout);
+test('self-defined retainer trace filter work as expected (part 2)', () => __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"]'); }),
+        retainerReferenceFilter: (edge) => {
+            return edge.name_or_index !== '_path_2';
+        },
+    };
+    const workDir = path_1.default.join(os_1.default.tmpdir(), 'memlab-api-test', (0, E2ETestSettings_1.getUniqueID)());
+    fs_extra_1.default.mkdirsSync(workDir);
+    const result = yield (0, index_1.run)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+        workDir,
+    });
+    // detected all different leak trace cluster
+    expect(result.leaks.length).toBe(1);
+    // expect the none of the traces to include _path_2
+    expect(result.leaks.every(leak => !JSON.stringify(leak).includes('_path_2')));
+    // expect some of the traces to include _path_1
+    expect(result.leaks.some(leak => JSON.stringify(leak).includes('_path_1')));
+    const reader = result.runResult;
+    expect(path_1.default.resolve(reader.getRootDirectory())).toBe(path_1.default.resolve(workDir));
+}), E2ETestSettings_1.testTimeout);

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,cAAc,4BAA4B,CAAC;AAC3C,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

@@ -47,6 +47,7 @@ function registerPackage() {
 exports.registerPackage = registerPackage;
 __exportStar(require("./API"), exports);
 __exportStar(require("@memlab/heap-analysis"), exports);
+__exportStar(require("./state/ConsoleModeManager"), 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");

package/dist/state/APIStateManager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { MemLabConfig, Optional, PuppeteerConfig } from '@memlab/core';
+import type { ConsoleMode } from './ConsoleModeManager';
+import type { RunOptions } from '../API';
+export declare class APIState {
+    modes: Optional<Set<ConsoleMode>>;
+    puppeteerConfig: Optional<PuppeteerConfig>;
+}
+/**
+ * Manage, save, and restore the current state of the API.
+ */
+declare class APIStateManager {
+    getAndUpdateState(config: MemLabConfig, options?: RunOptions): APIState;
+    restoreState(config: MemLabConfig, state: APIState): void;
+}
+declare const _default: APIStateManager;
+export default _default;
+//# sourceMappingURL=APIStateManager.d.ts.map

package/dist/state/APIStateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"APIStateManager.d.ts","sourceRoot":"","sources":["../../src/state/APIStateManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAC1E,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAKvC,qBAAa,QAAQ;IACnB,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;IAClC,eAAe,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,cAAM,eAAe;IACnB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,UAAe;IAUhE,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ;CAQnD;;AAED,wBAAqC"}

package/dist/state/APIStateManager.js

@@ -0,0 +1,40 @@
+"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 });
+exports.APIState = void 0;
+const ConsoleModeManager_1 = __importDefault(require("./ConsoleModeManager"));
+const PuppeteerConfigManager_1 = __importDefault(require("./PuppeteerConfigManager"));
+class APIState {
+}
+exports.APIState = APIState;
+/**
+ * Manage, save, and restore the current state of the API.
+ */
+class APIStateManager {
+    getAndUpdateState(config, options = {}) {
+        const state = new APIState();
+        state.modes = ConsoleModeManager_1.default.getAndUpdateState(config, options);
+        state.puppeteerConfig = PuppeteerConfigManager_1.default.getAndUpdateState(config, options);
+        return state;
+    }
+    restoreState(config, state) {
+        if (state.modes) {
+            ConsoleModeManager_1.default.restoreState(config, state.modes);
+        }
+        if (state.puppeteerConfig) {
+            PuppeteerConfigManager_1.default.restoreState(config, state.puppeteerConfig);
+        }
+    }
+}
+exports.default = new APIStateManager();

package/dist/state/ConsoleModeManager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { MemLabConfig, Nullable } from '@memlab/core';
+import type { RunOptions } from '../API';
+/**
+ * enum of all console mode options
+ */
+export declare enum ConsoleMode {
+    /**
+     * mute all terminal output, equivalent to using `--silent`
+     */
+    SILENT = "SILENT",
+    /**
+     * continuous test mode, no terminal output overwrite or animation,
+     * equivalent to using `--sc`
+     */
+    CONTINUOUS_TEST = "CONTINUOUS_TEST",
+    /**
+     * the default mode, there could be terminal output overwrite and animation,
+     */
+    DEFAULT = "DEFAULT",
+    /**
+     * verbose mode, there could be terminal output overwrite and animation
+     */
+    VERBOSE = "VERBOSE"
+}
+/**
+ * Manage, save, and restore the current state of the Console modes.
+ * @internal
+ */
+declare class ConsoleModeManager {
+    getAndUpdateState(config: MemLabConfig, options?: RunOptions): Nullable<Set<ConsoleMode>>;
+    restoreState(config: MemLabConfig, modes: Nullable<Set<ConsoleMode>>): void;
+    private resetConsoleMode;
+    private setConsoleMode;
+    private getExistingConsoleModes;
+}
+/** @internal */
+declare const _default: ConsoleModeManager;
+export default _default;
+//# sourceMappingURL=ConsoleModeManager.d.ts.map

package/dist/state/ConsoleModeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleModeManager.d.ts","sourceRoot":"","sources":["../../src/state/ConsoleModeManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,YAAY,EAAE,QAAQ,EAAkB,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAEvC;;GAEG;AACH,oBAAY,WAAW;IACrB;;OAEG;IACH,MAAM,WAAW;IACjB;;;OAGG;IACH,eAAe,oBAAoB;IACnC;;OAEG;IACH,OAAO,YAAY;IACnB;;OAEG;IACH,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,cAAM,kBAAkB;IACtB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,UAAe;IAIhE,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAUpE,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,cAAc;IAmCtB,OAAO,CAAC,uBAAuB;CAehC;AAED,gBAAgB;;AAChB,wBAAwC"}

package/dist/state/ConsoleModeManager.js

@@ -0,0 +1,106 @@
+"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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleMode = void 0;
+const core_1 = require("@memlab/core");
+/**
+ * enum of all console mode options
+ */
+var ConsoleMode;
+(function (ConsoleMode) {
+    /**
+     * mute all terminal output, equivalent to using `--silent`
+     */
+    ConsoleMode["SILENT"] = "SILENT";
+    /**
+     * continuous test mode, no terminal output overwrite or animation,
+     * equivalent to using `--sc`
+     */
+    ConsoleMode["CONTINUOUS_TEST"] = "CONTINUOUS_TEST";
+    /**
+     * the default mode, there could be terminal output overwrite and animation,
+     */
+    ConsoleMode["DEFAULT"] = "DEFAULT";
+    /**
+     * verbose mode, there could be terminal output overwrite and animation
+     */
+    ConsoleMode["VERBOSE"] = "VERBOSE";
+})(ConsoleMode = exports.ConsoleMode || (exports.ConsoleMode = {}));
+/**
+ * Manage, save, and restore the current state of the Console modes.
+ * @internal
+ */
+class ConsoleModeManager {
+    getAndUpdateState(config, options = {}) {
+        return this.setConsoleMode(config, options.consoleMode, true);
+    }
+    restoreState(config, modes) {
+        if (modes == null) {
+            return;
+        }
+        this.resetConsoleMode(config);
+        for (const mode of modes) {
+            this.setConsoleMode(config, mode, false);
+        }
+    }
+    resetConsoleMode(config) {
+        config.muteConsole = false;
+        config.isContinuousTest = false;
+        config.verbose = false;
+    }
+    setConsoleMode(config, mode, reset) {
+        let existingModes = this.getExistingConsoleModes(config);
+        switch (mode) {
+            case ConsoleMode.SILENT:
+                reset && this.resetConsoleMode(config);
+                config.muteConsole = true;
+                break;
+            case ConsoleMode.CONTINUOUS_TEST:
+                reset && this.resetConsoleMode(config);
+                config.isContinuousTest = true;
+                break;
+            case ConsoleMode.DEFAULT:
+                reset && this.resetConsoleMode(config);
+                config.muteConsole = false;
+                config.isContinuousTest = false;
+                break;
+            case ConsoleMode.VERBOSE:
+                reset && this.resetConsoleMode(config);
+                config.verbose = true;
+                break;
+            default:
+                if (mode == null) {
+                    existingModes = null;
+                }
+                else {
+                    throw core_1.utils.haltOrThrow(`Unknown console mode: ${mode}`);
+                }
+        }
+        return existingModes;
+    }
+    getExistingConsoleModes(config) {
+        const modes = new Set([ConsoleMode.DEFAULT]);
+        if (config.muteConsole) {
+            modes.add(ConsoleMode.SILENT);
+            modes.delete(ConsoleMode.DEFAULT);
+        }
+        if (config.isContinuousTest) {
+            modes.add(ConsoleMode.CONTINUOUS_TEST);
+            modes.delete(ConsoleMode.DEFAULT);
+        }
+        if (config.verbose) {
+            modes.add(ConsoleMode.VERBOSE);
+        }
+        return modes;
+    }
+}
+/** @internal */
+exports.default = new ConsoleModeManager();

package/dist/state/PuppeteerConfigManager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { MemLabConfig, PuppeteerConfig } from '@memlab/core';
+import type { RunOptions } from '../API';
+/**
+ * Manage, save, and restore the current state of the PuppeteerConfig.
+ */
+declare class PuppeteerStateManager {
+    getAndUpdateState(config: MemLabConfig, options?: RunOptions): PuppeteerConfig;
+    restoreState(config: MemLabConfig, puppeteerConfig: PuppeteerConfig): void;
+}
+declare const _default: PuppeteerStateManager;
+export default _default;
+//# sourceMappingURL=PuppeteerConfigManager.d.ts.map

package/dist/state/PuppeteerConfigManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PuppeteerConfigManager.d.ts","sourceRoot":"","sources":["../../src/state/PuppeteerConfigManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,QAAQ,CAAC;AAIvC;;GAEG;AACH,cAAM,qBAAqB;IACzB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,UAAe;IAWhE,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe;CAGpE;;AAED,wBAA2C"}

package/dist/state/PuppeteerConfigManager.js

@@ -0,0 +1,31 @@
+"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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+/**
+ * Manage, save, and restore the current state of the PuppeteerConfig.
+ */
+class PuppeteerStateManager {
+    getAndUpdateState(config, options = {}) {
+        const existing = config.puppeteerConfig;
+        config.puppeteerConfig = Object.assign({}, config.puppeteerConfig);
+        config.externalCookiesFile = options.cookiesFile;
+        config.scenario = options.scenario;
+        if (options.chromiumBinary != null) {
+            core_1.utils.setChromiumBinary(config, options.chromiumBinary);
+        }
+        return existing;
+    }
+    restoreState(config, puppeteerConfig) {
+        config.puppeteerConfig = puppeteerConfig;
+    }
+}
+exports.default = new PuppeteerStateManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/api",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "license": "MIT",
   "description": "memlab API",
   "author": "Liang Gong <lgong@fb.com>",
@@ -27,9 +27,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@memlab/core": "^1.1.10",
-    "@memlab/e2e": "^1.0.9",
-    "@memlab/heap-analysis": "^1.0.7",
+    "@memlab/core": "^1.1.28",
+    "@memlab/e2e": "^1.0.28",
+    "@memlab/heap-analysis": "^1.0.25",
     "ansi": "^0.3.1",
     "babar": "^0.2.0",
     "chalk": "^4.0.0",