@memlab/api 1.0.2 → 1.0.5

package/dist/__tests__/heap/examples/example-4.js

@@ -0,0 +1,32 @@
+"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 core_1 = require("@memlab/core");
+const heap_analysis_1 = require("@memlab/heap-analysis");
+(function () {
+    return __awaiter(this, void 0, void 0, function* () {
+        const heapFile = (0, core_1.dumpNodeHeapSnapshot)();
+        const heap = yield (0, heap_analysis_1.getHeapFromFile)(heapFile);
+        const node = heap.getNodeById(1);
+        if (node) {
+            console.log(node.id);
+        }
+    });
+})();

package/dist/__tests__/heap/examples/example-5.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=example-5.test.d.ts.map

package/dist/__tests__/heap/examples/example-5.test.js

@@ -0,0 +1,41 @@
+"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 core_1 = require("@memlab/core");
+class TestObject {
+    constructor() {
+        this.arr1 = [1, 2, 3];
+        this.arr2 = ['1', '2', '3'];
+    }
+}
+test('memory test', () => __awaiter(void 0, void 0, void 0, function* () {
+    core_1.config.muteConsole = true;
+    let obj = new TestObject();
+    // get a heap snapshot of the current program state
+    let heap = yield (0, core_1.getNodeInnocentHeap)();
+    // call some function that may add references to obj
+    // rabbitHole()
+    expect(heap.hasObjectWithClassName('TestObject')).toBe(true);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    obj = null;
+    heap = yield (0, core_1.getNodeInnocentHeap)();
+    // if rabbitHole does not add new references, the obj can be GCed
+    expect(heap.hasObjectWithClassName('TestObject')).toBe(false);
+}), 30000);

package/dist/__tests__/heap/examples/example-6.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=example-6.d.ts.map

package/dist/__tests__/heap/examples/example-6.js

@@ -0,0 +1,32 @@
+"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 core_1 = require("@memlab/core");
+const heap_analysis_1 = require("@memlab/heap-analysis");
+(function () {
+    return __awaiter(this, void 0, void 0, function* () {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const object = { 'memlab-test-heap-property': 'memlab-test-heap-value' };
+        const heapFile = (0, core_1.dumpNodeHeapSnapshot)();
+        const heap = yield (0, heap_analysis_1.getHeapFromFile)(heapFile);
+        // should be true
+        console.log(heap.hasObjectWithPropertyName('memlab-test-heap-property'));
+    });
+})();

package/dist/__tests__/heap/examples/example-7.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=example-7.test.d.ts.map

package/dist/__tests__/heap/examples/example-7.test.js

@@ -0,0 +1,36 @@
+"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 core_1 = require("@memlab/core");
+test('memory test', () => __awaiter(void 0, void 0, void 0, function* () {
+    core_1.config.muteConsole = true;
+    const o1 = {};
+    let o2 = {};
+    // tag o1 with marker: "memlab-mark-1"
+    (0, core_1.tagObject)(o1, 'memlab-mark-1');
+    // tag o2 with marker: "memlab-mark-2"
+    (0, core_1.tagObject)(o2, 'memlab-mark-2');
+    o2 = null;
+    const heap = yield (0, core_1.getNodeInnocentHeap)();
+    // expect object with marker "memlab-mark-1" exists
+    expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+    // expect object with marker "memlab-mark-2" can be GCed
+    expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+}), 30000);

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

@@ -7,8 +7,12 @@
  * @emails oncall+ws_labs
  * @format
  */
+/** @internal */
+export declare function registerPackage(): Promise<void>;
 export * from './API';
 export * from '@memlab/heap-analysis';
-export { config } from '@memlab/core';
 export { default as BrowserInteractionResultReader } from './result-reader/BrowserInteractionResultReader';
+export { dumpNodeHeapSnapshot, getNodeInnocentHeap } from '@memlab/core';
+/** @internal */
+export { config } from '@memlab/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,14 +22,36 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+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 });
-exports.BrowserInteractionResultReader = exports.config = void 0;
+exports.config = exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.BrowserInteractionResultReader = exports.registerPackage = void 0;
+const path_1 = __importDefault(require("path"));
+const core_1 = require("@memlab/core");
+/** @internal */
+function registerPackage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return core_1.PackageInfoLoader.registerPackage(path_1.default.join(__dirname, '..'));
+    });
+}
+exports.registerPackage = registerPackage;
 __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_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; } });
+/** @internal */
+var core_3 = require("@memlab/core");
+Object.defineProperty(exports, "config", { enumerable: true, get: function () { return core_3.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();