@memlab/api 1.0.21 → 1.0.23

package/dist/API.d.ts

@@ -138,7 +138,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
@@ -157,6 +157,21 @@ export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInte
  * ```
  */
 export declare function findLeaks(runResult: BrowserInteractionResultReader): 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.
@@ -169,7 +184,7 @@ export declare function findLeaks(runResult: BrowserInteractionResultReader): Pr
  * analysis class you are using for `heapAnalyzer`.
  * * **Examples**:
  * ```javascript
- * const {takeSnapshots, StringAnalysis} = require('@memlab/api');
+ * const {analyze, takeSnapshots, StringAnalysis} = require('@memlab/api');
  *
  * (async function () {
  *   const scenario = {

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"));
@@ -125,7 +125,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 +152,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.
@@ -164,7 +190,7 @@ exports.findLeaks = findLeaks;
  * analysis class you are using for `heapAnalyzer`.
  * * **Examples**:
  * ```javascript
- * const {takeSnapshots, StringAnalysis} = require('@memlab/api');
+ * const {analyze, takeSnapshots, StringAnalysis} = require('@memlab/api');
  *
  * (async function () {
  *   const scenario = {
@@ -309,30 +335,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 +376,9 @@ function testInBrowser(options = {}) {
                     }
                 });
             }
+            if (maybeError != null) {
+                core_1.utils.haltOrThrow(maybeError);
+            }
         }
     });
 }

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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/api",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "license": "MIT",
   "description": "memlab API",
   "author": "Liang Gong <lgong@fb.com>",