@memlab/api 1.0.2 → 1.0.3

package/dist/API.d.ts

@@ -8,18 +8,18 @@
  * @format
  */
 import type { ParsedArgs } from 'minimist';
-import type { AnyFunction, AnyValue, ISerializedInfo, IScenario } from '@memlab/core';
+import type { AnyFunction, ISerializedInfo, IScenario } from '@memlab/core';
 import { MemLabConfig } from '@memlab/core';
 import { TestPlanner } from '@memlab/e2e';
 import { BaseAnalysis } from '@memlab/heap-analysis';
 import BrowserInteractionResultReader from './result-reader/BrowserInteractionResultReader';
 /**
- * Options for configuring browser interaction run
+ * Options for configuring browser interaction run, all fields are optional
  */
 export declare type RunOptions = {
     /** test scenario definition */
     scenario?: IScenario;
-    /** cookies file */
+    /** the absolute path of cookies file */
     cookiesFile?: string;
     /** function to be evaluated in browser context after the web page initial load */
     evalInBrowserAfterInitLoad?: AnyFunction;
@@ -31,8 +31,8 @@ export declare type RunOptions = {
     snapshotForEachStep?: boolean;
 };
 /**
- * @ignore
  * Options for memlab inter-package API calls
+ * @internal
  */
 export declare type APIOptions = {
     testPlanner?: TestPlanner;
@@ -43,29 +43,61 @@ export declare type APIOptions = {
 /**
  * This API warms up web server, runs E2E interaction, and takes heap snapshots.
  * This is equivalent to run `memlab warmup-and-snapshot` in CLI.
- * This is also equivalent to call {@link warmup} and {@link takeSnapshots}.
+ * This is also equivalent to warm up and call {@link takeSnapshots}.
  *
  * @param options configure browser interaction run
  * @returns browser interaction results
+ * * **Examples**:
+ * ```javascript
+ * const {warmupAndTakeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await warmupAndTakeSnapshots({scenario});
+ * })();
+ * ```
  */
 export declare function warmupAndTakeSnapshots(options?: RunOptions): Promise<BrowserInteractionResultReader>;
 /**
  * This API runs browser interaction and find memory leaks triggered in browser
  * This is equivalent to run `memlab run` in CLI.
- * This is also equivalent to call {@link warmup}, {@link takeSnapshots},
+ * This is also equivalent to warm up, and call {@link takeSnapshots}
  * and {@link findLeaks}.
  *
- * @param options configure browser interaction run
- * @returns an array of leak traces detected and clustered from the
- * browser interaction
+ * @param runOptions configure browser interaction run
+ * @returns leak traces detected and clustered from the browser interaction
+ * * **Examples**:
+ * ```javascript
+ * const {run} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const leaks = await run({scenario});
+ * })();
+ * ```
  */
-export declare function run(options?: RunOptions): Promise<ISerializedInfo[]>;
+export declare function run(runOptions?: RunOptions): Promise<ISerializedInfo[]>;
 /**
  * This API runs E2E interaction and takes heap snapshots.
  * This is equivalent to run `memlab snapshot` in CLI.
  *
  * @param options configure browser interaction run
  * @returns browser interaction results
+ * * **Examples**:
+ * ```javascript
+ * const {takeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ * })();
+ * ```
  */
 export declare function takeSnapshots(options?: RunOptions): Promise<BrowserInteractionResultReader>;
 /**
@@ -73,8 +105,19 @@ 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
- * @returns an array of leak traces detected and clustered from the
- * browser interaction
+ * @returns leak traces detected and clustered from the browser interaction
+ * * **Examples**:
+ * ```javascript
+ * const {findLeaks, takeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ *   const leaks = findLeaks(result);
+ * })();
+ * ```
  */
 export declare function findLeaks(runResult: BrowserInteractionResultReader): Promise<ISerializedInfo[]>;
 /**
@@ -84,19 +127,35 @@ export declare function findLeaks(runResult: BrowserInteractionResultReader): Pr
  * @param runResult return value of a browser interaction run
  * @param heapAnalyzer instance of a heap analysis
  * @param args other CLI arguments that needs to be passed to the heap analysis
- * @returns
+ * @returns each analysis may have a different return type, please check out
+ * the type definition or the documentation for the `process` method of the
+ * analysis class you are using for `heapAnalyzer`.
+ * * **Examples**:
+ * ```javascript
+ * const {takeSnapshots, StringAnalysis} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ *   const analysis = new StringAnalysis();
+ *   await analyze(result, analysis);
+ * })();
+ * ```
  */
-export declare function analyze(runResult: BrowserInteractionResultReader, heapAnalyzer: BaseAnalysis, args?: ParsedArgs): Promise<AnyValue>;
+export declare function analyze(runResult: BrowserInteractionResultReader, heapAnalyzer: BaseAnalysis, args?: ParsedArgs): Promise<void>;
 /**
- * @ignore
  * This warms up web server by sending web requests to the web sever.
  * This is equivalent to run `memlab warmup` in CLI.
+ * @internal
  *
  * @param options configure browser interaction run
  */
 export declare function warmup(options?: APIOptions): Promise<void>;
 /**
- * @ignore
+ * Browser interaction API used by MemLab API and MemLab CLI
+ * @internal
  */
 export declare function testInBrowser(options?: APIOptions): Promise<void>;
 //# sourceMappingURL=API.d.ts.map

package/dist/API.js

@@ -29,10 +29,21 @@ const BrowserInteractionResultReader_1 = __importDefault(require("./result-reade
 /**
  * This API warms up web server, runs E2E interaction, and takes heap snapshots.
  * This is equivalent to run `memlab warmup-and-snapshot` in CLI.
- * This is also equivalent to call {@link warmup} and {@link takeSnapshots}.
+ * This is also equivalent to warm up and call {@link takeSnapshots}.
  *
  * @param options configure browser interaction run
  * @returns browser interaction results
+ * * **Examples**:
+ * ```javascript
+ * const {warmupAndTakeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await warmupAndTakeSnapshots({scenario});
+ * })();
+ * ```
  */
 function warmupAndTakeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -51,21 +62,31 @@ exports.warmupAndTakeSnapshots = warmupAndTakeSnapshots;
 /**
  * This API runs browser interaction and find memory leaks triggered in browser
  * This is equivalent to run `memlab run` in CLI.
- * This is also equivalent to call {@link warmup}, {@link takeSnapshots},
+ * This is also equivalent to warm up, and call {@link takeSnapshots}
  * and {@link findLeaks}.
  *
- * @param options configure browser interaction run
- * @returns an array of leak traces detected and clustered from the
- * browser interaction
+ * @param runOptions configure browser interaction run
+ * @returns leak traces detected and clustered from the browser interaction
+ * * **Examples**:
+ * ```javascript
+ * const {run} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const leaks = await run({scenario});
+ * })();
+ * ```
  */
-function run(options = {}) {
+function run(runOptions = {}) {
     return __awaiter(this, void 0, void 0, function* () {
         const config = core_1.MemLabConfig.resetConfigWithTranscientDir();
-        setConfigByRunOptions(config, options);
-        config.externalCookiesFile = options.cookiesFile;
-        config.scenario = options.scenario;
+        setConfigByRunOptions(config, runOptions);
+        config.externalCookiesFile = runOptions.cookiesFile;
+        config.scenario = runOptions.scenario;
         const testPlanner = new e2e_1.TestPlanner({ config });
-        const { evalInBrowserAfterInitLoad } = options;
+        const { evalInBrowserAfterInitLoad } = runOptions;
         yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
         const runResult = BrowserInteractionResultReader_1.default.from(config.workDir);
@@ -79,6 +100,17 @@ exports.run = run;
  *
  * @param options configure browser interaction run
  * @returns browser interaction results
+ * * **Examples**:
+ * ```javascript
+ * const {takeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ * })();
+ * ```
  */
 function takeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -98,8 +130,19 @@ exports.takeSnapshots = takeSnapshots;
  * This is equivalent to `memlab find-leaks` in CLI.
  *
  * @param runResult return value of a browser interaction run
- * @returns an array of leak traces detected and clustered from the
- * browser interaction
+ * @returns leak traces detected and clustered from the browser interaction
+ * * **Examples**:
+ * ```javascript
+ * const {findLeaks, takeSnapshots} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ *   const leaks = findLeaks(result);
+ * })();
+ * ```
  */
 function findLeaks(runResult) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -117,7 +160,22 @@ exports.findLeaks = findLeaks;
  * @param runResult return value of a browser interaction run
  * @param heapAnalyzer instance of a heap analysis
  * @param args other CLI arguments that needs to be passed to the heap analysis
- * @returns
+ * @returns each analysis may have a different return type, please check out
+ * the type definition or the documentation for the `process` method of the
+ * analysis class you are using for `heapAnalyzer`.
+ * * **Examples**:
+ * ```javascript
+ * const {takeSnapshots, StringAnalysis} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *   };
+ *   const result = await takeSnapshots({scenario});
+ *   const analysis = new StringAnalysis();
+ *   await analyze(result, analysis);
+ * })();
+ * ```
  */
 function analyze(runResult, heapAnalyzer, args = { _: [] }) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -128,9 +186,9 @@ function analyze(runResult, heapAnalyzer, args = { _: [] }) {
 }
 exports.analyze = analyze;
 /**
- * @ignore
  * This warms up web server by sending web requests to the web sever.
  * This is equivalent to run `memlab warmup` in CLI.
+ * @internal
  *
  * @param options configure browser interaction run
  */
@@ -221,7 +279,8 @@ function initBrowserInfoInConfig(browser, options = {}) {
     });
 }
 /**
- * @ignore
+ * Browser interaction API used by MemLab API and MemLab CLI
+ * @internal
  */
 function testInBrowser(options = {}) {
     var _a, _b;

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

@@ -18,13 +18,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable @typescript-eslint/ban-ts-comment */
 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'));
@@ -35,6 +36,8 @@ function injectDetachedDOMElements() {
         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* () {
@@ -49,3 +52,21 @@ 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 leaks = yield (0, index_1.run)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectDetachedDOMElements,
+    });
+    // detected all different leak trace cluster
+    expect(leaks.length).toBe(1);
+    // expect all traces are found
+    expect(leaks.some(leak => JSON.stringify(leak).includes('_randomObject')));
+}), E2ETestSettings_1.testTimeout);

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

@@ -47,12 +47,14 @@ test('Shape unbound analysis works as expected', () => __awaiter(void 0, void 0,
     });
     // test analysis from auto loading
     let analysis = new index_1.ShapeUnboundGrowthAnalysis();
-    let shapeSummary = yield analysis.run();
+    yield analysis.run();
+    let shapeSummary = analysis.getShapesWithUnboundGrowth();
     expect(shapeSummary.reduce((acc, summary) => acc || summary.shape.includes('LeakObject'), false)).toBe(true);
     // test analysis from file
     const snapshotDir = result.getSnapshotFileDir();
     analysis = new index_1.ShapeUnboundGrowthAnalysis();
-    shapeSummary = yield analysis.analyzeSnapshotsInDirectory(snapshotDir);
+    yield analysis.analyzeSnapshotsInDirectory(snapshotDir);
+    shapeSummary = analysis.getShapesWithUnboundGrowth();
     expect(shapeSummary.some((summary) => summary.shape.includes('LeakObject'))).toBe(true);
     // expect incorrect use of heap analysis to throw
     const snapshotFile = result.getSnapshotFiles().pop();

package/dist/__tests__/packages/heap-analysis.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.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+export {};
+//# sourceMappingURL=heap-analysis.test.d.ts.map

package/dist/__tests__/packages/heap-analysis.test.js

@@ -0,0 +1,82 @@
+"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.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+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 heap_analysis_1 = require("@memlab/heap-analysis");
+const index_1 = require("../../index");
+const E2ETestSettings_1 = require("../API/lib/E2ETestSettings");
+const API_1 = require("../../API");
+beforeEach(E2ETestSettings_1.testSetup);
+function injectTestObject() {
+    class TestObject {
+    }
+    // @ts-ignore
+    window.injectHookForLink4 = () => {
+        // @ts-ignore
+        const arr = (window.__injectedValue = window.__injectedValue || []);
+        arr.push(new TestObject());
+    };
+}
+const selfDefinedScenario = {
+    app: () => 'test-spa',
+    url: () => '',
+    action: (page) => __awaiter(void 0, void 0, void 0, function* () { return yield page.click('[data-testid="link-4"]'); }),
+    repeat: () => 3,
+};
+class ExampleAnalysis extends heap_analysis_1.BaseAnalysis {
+    constructor() {
+        super(...arguments);
+        this.isMonotonicIncreasing = false;
+    }
+    getCommandName() {
+        return 'example-analysis';
+    }
+    getDescription() {
+        return 'an example analysis for demo';
+    }
+    process(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // check if the number of TestObject keeps growing overtime
+            this.isMonotonicIncreasing = yield (0, heap_analysis_1.snapshotMapReduce)(heap => {
+                let cnt = 0;
+                heap.nodes.forEach(node => {
+                    if (node.name === 'TestObject' && node.type === 'object') {
+                        ++cnt;
+                    }
+                });
+                return cnt;
+            }, nodeCounts => nodeCounts[0] === 0 &&
+                nodeCounts[nodeCounts.length - 1] === 4 &&
+                nodeCounts.every((count, i) => i === 0 || count >= nodeCounts[i - 1]), options);
+        });
+    }
+}
+test('snapshotMapReduce works as expected', () => __awaiter(void 0, void 0, void 0, function* () {
+    const results = yield (0, API_1.takeSnapshots)({
+        scenario: selfDefinedScenario,
+        evalInBrowserAfterInitLoad: injectTestObject,
+        snapshotForEachStep: true,
+    });
+    let analysis = new ExampleAnalysis();
+    yield (0, index_1.analyze)(results, analysis);
+    expect(analysis.isMonotonicIncreasing).toBe(true);
+    analysis = new ExampleAnalysis();
+    yield analysis.analyzeSnapshotsInDirectory(results.getSnapshotFileDir());
+    expect(analysis.isMonotonicIncreasing).toBe(true);
+}), E2ETestSettings_1.testTimeout);

package/dist/index.d.ts

@@ -9,6 +9,8 @@
  */
 export * from './API';
 export * from '@memlab/heap-analysis';
-export { config } from '@memlab/core';
 export { default as BrowserInteractionResultReader } from './result-reader/BrowserInteractionResultReader';
+export { dumpNodeHeapSnapshot, getCurrentNodeHeap } from '@memlab/core';
+/** @internal */
+export { config } from '@memlab/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -26,10 +26,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BrowserInteractionResultReader = exports.config = void 0;
+exports.config = exports.getCurrentNodeHeap = exports.dumpNodeHeapSnapshot = exports.BrowserInteractionResultReader = void 0;
 __exportStar(require("./API"), exports);
 __exportStar(require("@memlab/heap-analysis"), exports);
-var core_1 = require("@memlab/core");
-Object.defineProperty(exports, "config", { enumerable: true, get: function () { return core_1.config; } });
 var BrowserInteractionResultReader_1 = require("./result-reader/BrowserInteractionResultReader");
 Object.defineProperty(exports, "BrowserInteractionResultReader", { enumerable: true, get: function () { return __importDefault(BrowserInteractionResultReader_1).default; } });
+var core_1 = require("@memlab/core");
+Object.defineProperty(exports, "dumpNodeHeapSnapshot", { enumerable: true, get: function () { return core_1.dumpNodeHeapSnapshot; } });
+Object.defineProperty(exports, "getCurrentNodeHeap", { enumerable: true, get: function () { return core_1.getCurrentNodeHeap; } });
+/** @internal */
+var core_2 = require("@memlab/core");
+Object.defineProperty(exports, "config", { enumerable: true, get: function () { return core_2.config; } });

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

@@ -14,11 +14,8 @@ import { FileManager } from '@memlab/core';
  * a memlab run
  */
 export default class BaseResultReader {
-    /** @ignore */
     protected workDir: string;
-    /** @ignore */
     protected fileManager: FileManager;
-    /** @ignore */
     private isValid;
     /**
      * build a result reader
@@ -26,23 +23,47 @@ export default class BaseResultReader {
      * and generated files of the memlab run were stored
      */
     protected constructor(workDir?: string);
-    /** @ignore */
     protected check(): void;
     /**
-     * build a result reader
-     * @param workDir absolute path of the directory where the data
-     * and generated files of the memlab run were stored
-     * @returns the ResultReader instance
+     * internal
+     * @param workDir
+     * @returns
      */
     static from(workDir?: string): BaseResultReader;
     /**
      * get the directory where the data and generated files of
      * the memlab run were stored
      * @returns absolute path of the directory
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get the directory that stores all the files
+     *   // generated from the takeSnapshots call
+     *   const dataDir = result.getRootDirectory();
+     * })();
+     * ```
      */
     getRootDirectory(): string;
     /**
-     * clean up data/files generated from the memlab run
+     * clean up data/files generated from the memlab browser interaction run
+     * @returns no return value
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // delete all data/files generated by takeSnapshots
+     *   result.cleanup();
+     * })();
+     * ```
      */
     cleanup(): void;
 }

package/dist/result-reader/BaseResultReader.js

@@ -33,7 +33,6 @@ class BaseResultReader {
         this.workDir = workDir;
         this.check();
     }
-    /** @ignore */
     check() {
         this.isValid = fs_extra_1.default.existsSync(this.workDir);
         if (!this.isValid) {
@@ -41,10 +40,9 @@ class BaseResultReader {
         }
     }
     /**
-     * build a result reader
-     * @param workDir absolute path of the directory where the data
-     * and generated files of the memlab run were stored
-     * @returns the ResultReader instance
+     * internal
+     * @param workDir
+     * @returns
      */
     static from(workDir = '') {
         return new BaseResultReader(workDir);
@@ -53,13 +51,39 @@ class BaseResultReader {
      * get the directory where the data and generated files of
      * the memlab run were stored
      * @returns absolute path of the directory
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get the directory that stores all the files
+     *   // generated from the takeSnapshots call
+     *   const dataDir = result.getRootDirectory();
+     * })();
+     * ```
      */
     getRootDirectory() {
         this.check();
         return this.workDir;
     }
     /**
-     * clean up data/files generated from the memlab run
+     * clean up data/files generated from the memlab browser interaction run
+     * @returns no return value
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // delete all data/files generated by takeSnapshots
+     *   result.cleanup();
+     * })();
+     * ```
      */
     cleanup() {
         if (!this.isValid) {

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

@@ -16,30 +16,89 @@ import BaseResultReader from './BaseResultReader';
  */
 export default class BrowserInteractionResultReader extends BaseResultReader {
     /**
-     * build a result reader
-     * @param workDir absolute path of the directory where the data
-     * and generated files of the browser interaction run were stored
+     * build a result reader from a data directory where the data
+     * and generated files of a memlab run were stored
+     * @param workDir absolute path of the data directory
      * @returns the ResultReader instance
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {BrowserInteractionResultReader} = require('@memlab/api');
+     *
+     * const dataDir = '/tmp/memlab'; // where the last memlab run stores results
+     * const reader = BrowserInteractionResultReader.from(dataDir);
+     * reader.cleanup(); // clean up the results
+     * ```
      */
     static from(workDir?: string): BrowserInteractionResultReader;
     /**
-     * get all snapshot files
+     * get all snapshot files generated from last memlab browser interaction
      * @returns an array of snapshot file's absolute path
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get absolute paths of all snapshot files
+     *   const files = result.getSnapshotFiles();
+     * })();
+     * ```
      */
     getSnapshotFiles(): string[];
     /**
      * get the directory holding all snapshot files
      * @returns the absolute path of the directory
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get the absolute path the directory holding all snapshot files
+     *   const files = result.getSnapshotFileDir();
+     * })();
+     * ```
      */
     getSnapshotFileDir(): string;
     /**
      * browser interaction step sequence
-     * @returns an array of browser interaction step info
+     * @returns an array of browser interaction step information
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   const steps = result.getInteractionSteps();
+     *   // print each browser interaction's name and JavaScript heap size (in bytes)
+     *   steps.forEach(step => console.log(step.name, step.JSHeapUsedSize))
+     * })();
+     * ```
      */
     getInteractionSteps(): E2EStepInfo[];
     /**
      * general meta data of the browser interaction run
      * @returns meta data about the entire browser interaction
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   const metaInfo = result.getRunMetaInfo();
+     *   // print all browser web console output
+     *   console.log(metaInfo.browserInfo._consoleMessages.join('\n'));
+     * })();
+     * ```
      */
     getRunMetaInfo(): RunMetaInfo;
 }

package/dist/result-reader/BrowserInteractionResultReader.js

@@ -23,17 +23,38 @@ const BaseResultReader_1 = __importDefault(require("./BaseResultReader"));
  */
 class BrowserInteractionResultReader extends BaseResultReader_1.default {
     /**
-     * build a result reader
-     * @param workDir absolute path of the directory where the data
-     * and generated files of the browser interaction run were stored
+     * build a result reader from a data directory where the data
+     * and generated files of a memlab run were stored
+     * @param workDir absolute path of the data directory
      * @returns the ResultReader instance
+     *
+     * * **Examples**:
+     * ```javascript
+     * const {BrowserInteractionResultReader} = require('@memlab/api');
+     *
+     * const dataDir = '/tmp/memlab'; // where the last memlab run stores results
+     * const reader = BrowserInteractionResultReader.from(dataDir);
+     * reader.cleanup(); // clean up the results
+     * ```
      */
     static from(workDir = '') {
         return new BrowserInteractionResultReader(workDir);
     }
     /**
-     * get all snapshot files
+     * get all snapshot files generated from last memlab browser interaction
      * @returns an array of snapshot file's absolute path
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get absolute paths of all snapshot files
+     *   const files = result.getSnapshotFiles();
+     * })();
+     * ```
      */
     getSnapshotFiles() {
         this.check();
@@ -46,6 +67,18 @@ class BrowserInteractionResultReader extends BaseResultReader_1.default {
     /**
      * get the directory holding all snapshot files
      * @returns the absolute path of the directory
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   // get the absolute path the directory holding all snapshot files
+     *   const files = result.getSnapshotFileDir();
+     * })();
+     * ```
      */
     getSnapshotFileDir() {
         this.check();
@@ -53,7 +86,20 @@ class BrowserInteractionResultReader extends BaseResultReader_1.default {
     }
     /**
      * browser interaction step sequence
-     * @returns an array of browser interaction step info
+     * @returns an array of browser interaction step information
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   const steps = result.getInteractionSteps();
+     *   // print each browser interaction's name and JavaScript heap size (in bytes)
+     *   steps.forEach(step => console.log(step.name, step.JSHeapUsedSize))
+     * })();
+     * ```
      */
     getInteractionSteps() {
         this.check();
@@ -65,6 +111,19 @@ class BrowserInteractionResultReader extends BaseResultReader_1.default {
     /**
      * general meta data of the browser interaction run
      * @returns meta data about the entire browser interaction
+     * * **Examples**:
+     * ```javascript
+     * const {takeSnapshots} = require('@memlab/api');
+     *
+     * (async function () {
+     *   const scenario = { url: () => 'https://www.npmjs.com'};
+     *   const result = await takeSnapshots({scenario});
+     *
+     *   const metaInfo = result.getRunMetaInfo();
+     *   // print all browser web console output
+     *   console.log(metaInfo.browserInfo._consoleMessages.join('\n'));
+     * })();
+     * ```
      */
     getRunMetaInfo() {
         this.check();

package/package.json

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

package/dist/API.d.ts.map

@@ -1 +0,0 @@
-{"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,QAAQ,EACR,eAAe,EACf,SAAS,EAGV,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;AAE5F;;GAEG;AACH,oBAAY,UAAU,GAAG;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,0BAA0B,CAAC,EAAE,WAAW,CAAC;IACzC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,oBAAY,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;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,8BAA8B,CAAC,CAUzC;AAED;;;;;;;;;GASG;AACH,wBAAsB,GAAG,CACvB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAW5B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,8BAA8B,CAAC,CASzC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,8BAA8B,GACxC,OAAO,CAAC,eAAe,EAAE,CAAC,CAK5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,8BAA8B,EACzC,YAAY,EAAE,YAAY,EAC1B,IAAI,GAAE,UAAoB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAInB;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpE;AAsDD;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD3E"}

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

@@ -1 +0,0 @@
-{"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

@@ -1 +0,0 @@
-{"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

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

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

@@ -1 +0,0 @@
-{"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

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

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

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

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

@@ -1 +0,0 @@
-{"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

@@ -1 +0,0 @@
-{"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

@@ -1 +0,0 @@
-{"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

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

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

@@ -1 +0,0 @@
-{"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"}

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

@@ -1 +0,0 @@
-{"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;AAOrE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,EAAE,QAAQ,CAAC;KACpB;CACF"}

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

@@ -1 +0,0 @@
-{"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/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,OAAO,CAAC;AACtB,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAC,MAAM,EAAC,MAAM,cAAc,CAAC;AACpC,OAAO,EAAC,OAAO,IAAI,8BAA8B,EAAC,MAAM,gDAAgD,CAAC"}

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

@@ -1 +0,0 @@
-{"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,CAmBlB;;;;AAED,wBAEE"}

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

@@ -1 +0,0 @@
-{"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,cAAc;IACd,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,cAAc;IACd,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;IACnC,cAAc;IACd,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;OAIG;IACH,SAAS,aAAa,OAAO,SAAK;IASlC,cAAc;IACd,SAAS,CAAC,KAAK,IAAI,IAAI;IAOvB;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,SAAK,GAAG,gBAAgB;IAI3C;;;;OAIG;IACI,gBAAgB,IAAI,MAAM;IAKjC;;OAEG;IACI,OAAO,IAAI,IAAI;CAOvB"}

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

@@ -1 +0,0 @@
-{"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;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,SAAK,GAAG,8BAA8B;IAIzD;;;OAGG;IACI,gBAAgB,IAAI,MAAM,EAAE;IASnC;;;OAGG;IACI,kBAAkB,IAAI,MAAM;IAKnC;;;OAGG;IACI,mBAAmB,IAAI,WAAW,EAAE;IAQ3C;;;OAGG;IACI,cAAc,IAAI,WAAW;CAOrC"}