@memlab/api 1.0.4 → 1.0.5

package/README.md

@@ -3,5 +3,6 @@
 This is the memlab API library. Add this dependency to your project
 if you want to integrate memlab with your continuous testing system.
 
-## Full documentation
-https://facebookincubator.github.io/memlab
+## Online Resources
+* [Official Website and Demo](https://facebookincubator.github.io/memlab)
+* [Documentation](https://facebookincubator.github.io/memlab/docs/intro)

package/dist/API.d.ts

@@ -24,7 +24,10 @@ export declare type RunOptions = {
     scenario?: IScenario;
     /** the absolute path of cookies file */
     cookiesFile?: string;
-    /** function to be evaluated in browser context after the web page initial load */
+    /**
+     * function to be evaluated in browser context after
+     * the web page initial load
+     */
     evalInBrowserAfterInitLoad?: AnyFunction;
     /**
      * if true, take heap snapshot for each interaction step,
@@ -32,6 +35,29 @@ export declare type RunOptions = {
      * which steps it will take heap snapshots
      */
     snapshotForEachStep?: boolean;
+    /**
+     * specify the working directory where you want memlab to dump
+     * heap snapshots and other meta data of the test run. If no
+     * working directory is provided, memlab will generate a random
+     * temp directory under the operating system's default directory
+     * for temporary files.
+     * Note: It's the caller's responsibility to make sure the
+     * specified working directory exists.
+     */
+    workDir?: string;
+};
+/**
+ * A data structure holding the result of the {@link run} API call.
+ */
+export declare type RunResult = {
+    /**
+     * leak traces detected and clustered from the browser interaction
+     */
+    leaks: ISerializedInfo[];
+    /**
+     * a utility for reading browser interaction results from disk
+     */
+    runResult: BrowserInteractionResultReader;
 };
 /**
  * Options for memlab inter-package API calls
@@ -70,7 +96,8 @@ export declare function warmupAndTakeSnapshots(options?: RunOptions): Promise<Br
  * and {@link findLeaks}.
  *
  * @param runOptions configure browser interaction run
- * @returns leak traces detected and clustered from the browser interaction
+ * @returns memory leaks detected and a utility reading browser
+ * interaction results from disk
  * * **Examples**:
  * ```javascript
  * const {run} = require('@memlab/api');
@@ -79,17 +106,17 @@ export declare function warmupAndTakeSnapshots(options?: RunOptions): Promise<Br
  *   const scenario = {
  *     url: () => 'https://www.facebook.com',
  *   };
- *   const leaks = await run({scenario});
+ *   const {leaks} = await run({scenario});
  * })();
  * ```
  */
-export declare function run(runOptions?: RunOptions): Promise<ISerializedInfo[]>;
+export declare function run(runOptions?: RunOptions): Promise<RunResult>;
 /**
  * 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
+ * @returns a utility reading browser interaction results from disk
  * * **Examples**:
  * ```javascript
  * const {takeSnapshots} = require('@memlab/api');

package/dist/API.js

@@ -47,8 +47,7 @@ const BrowserInteractionResultReader_1 = __importDefault(require("./result-reade
  */
 function warmupAndTakeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const config = core_1.MemLabConfig.resetConfigWithTranscientDir();
-        setConfigByRunOptions(config, options);
+        const config = getConfigFromRunOptions(options);
         config.externalCookiesFile = options.cookiesFile;
         config.scenario = options.scenario;
         const testPlanner = new e2e_1.TestPlanner({ config });
@@ -66,7 +65,8 @@ exports.warmupAndTakeSnapshots = warmupAndTakeSnapshots;
  * and {@link findLeaks}.
  *
  * @param runOptions configure browser interaction run
- * @returns leak traces detected and clustered from the browser interaction
+ * @returns memory leaks detected and a utility reading browser
+ * interaction results from disk
  * * **Examples**:
  * ```javascript
  * const {run} = require('@memlab/api');
@@ -75,14 +75,13 @@ exports.warmupAndTakeSnapshots = warmupAndTakeSnapshots;
  *   const scenario = {
  *     url: () => 'https://www.facebook.com',
  *   };
- *   const leaks = await run({scenario});
+ *   const {leaks} = await run({scenario});
  * })();
  * ```
  */
 function run(runOptions = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const config = core_1.MemLabConfig.resetConfigWithTranscientDir();
-        setConfigByRunOptions(config, runOptions);
+        const config = getConfigFromRunOptions(runOptions);
         config.externalCookiesFile = runOptions.cookiesFile;
         config.scenario = runOptions.scenario;
         const testPlanner = new e2e_1.TestPlanner({ config });
@@ -90,7 +89,8 @@ function run(runOptions = {}) {
         yield warmup({ testPlanner, config, evalInBrowserAfterInitLoad });
         yield testInBrowser({ testPlanner, config, evalInBrowserAfterInitLoad });
         const runResult = BrowserInteractionResultReader_1.default.from(config.workDir);
-        return yield findLeaks(runResult);
+        const leaks = yield findLeaks(runResult);
+        return { leaks, runResult };
     });
 }
 exports.run = run;
@@ -99,7 +99,7 @@ exports.run = run;
  * This is equivalent to run `memlab snapshot` in CLI.
  *
  * @param options configure browser interaction run
- * @returns browser interaction results
+ * @returns a utility reading browser interaction results from disk
  * * **Examples**:
  * ```javascript
  * const {takeSnapshots} = require('@memlab/api');
@@ -114,8 +114,7 @@ exports.run = run;
  */
 function takeSnapshots(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const config = core_1.MemLabConfig.resetConfigWithTranscientDir();
-        setConfigByRunOptions(config, options);
+        const config = getConfigFromRunOptions(options);
         config.externalCookiesFile = options.cookiesFile;
         config.scenario = options.scenario;
         const testPlanner = new e2e_1.TestPlanner();
@@ -232,8 +231,16 @@ function warmup(options = {}) {
     });
 }
 exports.warmup = warmup;
-function setConfigByRunOptions(config, options) {
+function getConfigFromRunOptions(options) {
+    let config = core_1.MemLabConfig.getInstance();
+    if (options.workDir) {
+        core_1.fileManager.initDirs(config, { workDir: options.workDir });
+    }
+    else {
+        config = core_1.MemLabConfig.resetConfigWithTranscientDir();
+    }
     config.isFullRun = !!options.snapshotForEachStep;
+    return config;
 }
 function setupPage(page, options = {}) {
     var _a, _b, _c;

package/dist/__tests__/API/E2EFindLeaks.example.js

@@ -43,7 +43,7 @@ function inject() {
 }
 function test() {
     return __awaiter(this, void 0, void 0, function* () {
-        const leaks = yield (0, index_1.run)({ scenario, evalInBrowserAfterInitLoad: inject });
+        const { leaks } = yield (0, index_1.run)({ scenario, evalInBrowserAfterInitLoad: inject });
         core_1.info.lowLevel(`${leaks.length}`);
     });
 }

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

@@ -17,7 +17,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         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);
@@ -41,12 +47,12 @@ function injectDetachedDOMElements() {
     };
 }
 test('leak detector can find detached DOM elements', () => __awaiter(void 0, void 0, void 0, function* () {
-    const leaks = yield (0, index_1.run)({
+    const { leaks } = yield (0, index_1.run)({
         scenario: E2ETestSettings_1.scenario,
         evalInBrowserAfterInitLoad: injectDetachedDOMElements,
     });
     // detected all different leak trace cluster
-    expect(leaks.length).toBe(3);
+    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')));
@@ -61,12 +67,17 @@ test('self-defined leak detector can find TestObject', () => __awaiter(void 0, v
             return node.name === 'TestObject' && node.type === 'object';
         },
     };
-    const leaks = yield (0, index_1.run)({
+    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(leaks.length).toBe(1);
+    expect(result.leaks.length).toBe(1);
     // expect all traces are found
-    expect(leaks.some(leak => JSON.stringify(leak).includes('_randomObject')));
+    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);

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  * @emails oncall+ws_labs
  * @format
  */
+/** @internal */
+export declare function registerPackage(): Promise<void>;
 export * from './API';
 export * from '@memlab/heap-analysis';
 export { default as BrowserInteractionResultReader } from './result-reader/BrowserInteractionResultReader';

package/dist/index.js

@@ -22,18 +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.config = exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.BrowserInteractionResultReader = 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 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, "getNodeInnocentHeap", { enumerable: true, get: function () { return core_1.getNodeInnocentHeap; } });
-/** @internal */
 var core_2 = require("@memlab/core");
-Object.defineProperty(exports, "config", { enumerable: true, get: function () { return core_2.config; } });
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/api",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "license": "MIT",
   "description": "memlab API",
   "author": "Liang Gong <lgong@fb.com>",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@memlab/core": "^1.0.0",
+    "@memlab/core": "^1.1.5",
     "@memlab/e2e": "^1.0.0",
     "@memlab/heap-analysis": "^1.0.0",
     "ansi": "^0.3.1",