memlab 1.0.0-alpha → 1.0.4-alpha

package/README.md

@@ -1,11 +1,83 @@
-# `memlab`
+# memlab
 
-> TODO: description
+memlab is an E2E testing and analysis framework for finding memory leaks
+in-browser JavaScript Code. The CLI Toolbox and library provide extensible
+interfaces for analyzing heap snapshots taken from Chrome, Node.js, Hermes,
+and Electron.js.
 
-## Usage
+## CLI Usage
 
+Install the CLI
+
+```bash
+npm install -g @memlab
+```
+
+To find memory leaks in Google Maps, create a scenario file defining how
+we want to interact with the Google Maps, let's name it `test-google-maps.js`:
+
+```
+// Visit Google Maps
+function url() {
+  return 'https://www.google.com/maps/@37.386427,-122.0428214,11z';
+}
+
+// action where we want to detect memory leaks: click the Hotels button
+async function action(page) {
+  await page.click('button[aria-label="Hotels"]');
+}
+
+// action where we want to go back to the step before: click clear search
+async function back(page) {
+  await page.click('[aria-label="Clear search"]');
+}
+
+module.exports = {action, back, url};
+```
+
+Now run memlab with the scenario file, memlab will interaction with
+the web page and show detected memory leaks:
+
+```bash
+memlab run --scenario test-google-maps.js
+```
+
+View which object keeps growing in size during interaction in the previous run:
+```bash
+memlab analyze unbound-object
 ```
-const api = require('memlab');
 
-// TODO: DEMONSTRATE API
+Analyze pre-fetched v8/hermes `.heapsnapshot` files:
+
+```bash
+memlab analyze unbound-object --snapshot-dir <DIR_OF_SNAPSHOT_FILES>
+```
+
+Use `memlab analyze` to view all memory analyses. For extension, view the [doc site](/tba).
+
+View retain trace of a particular object:
+```bash
+memlab report --nodeId <HEAP_OBJECT_ID>
+```
+
+Use `memlab help` to view all CLI commands.
+
+## APIs
+
+Use the `memlab` library to start a E2E run in browser and detect memory leaks.
+
+```javascript
+const memlab = require('memlab');
+
+const scenario = {
+    // initial page load url
+    url: () => 'https://www.google.com/maps/@37.386427,-122.0428214,11z',
+
+    // action where we want to detect memory leaks
+    action: async (page) => await page.click('button[aria-label="Hotels"]'),
+
+    // action where we want to go back to the step before
+    back: async (page) => await page.click('[aria-label="Clear search"]'),
+}
+memlab.run({scenario});
 ```

package/package.json

@@ -1,10 +1,6 @@
 {
   "name": "memlab",
-  "version": "1.0.0-alpha",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/facebookincubator/memlab.git"
-  },
+  "version": "1.0.4-alpha",
   "license": "MIT",
   "description": "memlab is a framework that analyzes memory and finds memory leaks in JavaScript applications.",
   "main": "dist/index.js",
@@ -68,6 +64,10 @@
     "./packages/api",
     "./packages/cli"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facebookincubator/memlab.git"
+  },
   "bugs": {
     "url": "https://github.com/facebookincubator/memlab/issues"
   },