@memlab/api 2.0.6 → 2.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +132 -3
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,8 +1,137 @@
1
- ## memlab API
1
+ # @memlab/api
2
2
 
3
- This is the memlab API library. Add this dependency to your project
4
- if you want to integrate memlab with your continuous testing system.
3
+ The memlab API for Node.js. Use it to run memlab from code, for example from
4
+ a continuous test job, instead of through the `memlab` CLI.
5
+
6
+ It drives a web page in Chromium through [Puppeteer](https://pptr.dev/), takes
7
+ JavaScript heap snapshots, finds memory leaks, and runs heap analyses. Results
8
+ come back as objects you can inspect, assert on, or store.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm install @memlab/api
14
+ ```
15
+
16
+ ## Find memory leaks in a web page
17
+
18
+ A [test scenario](https://meta.github.io/memlab/docs/api/core/src/interfaces/IScenario)
19
+ describes the page to load (`url`), the interaction you suspect leaks memory
20
+ (`action`), and how to undo it (`back`). `run` loads the page, runs the
21
+ interaction, takes a heap snapshot after each step, and returns the leaks it
22
+ found, clustered by retainer trace:
23
+
24
+ ```javascript
25
+ const {run} = require('@memlab/api');
26
+
27
+ (async function () {
28
+ const scenario = {
29
+ url: () => 'https://www.google.com/maps/@37.386427,-122.0428214,11z',
30
+ action: async page => await page.click('text/Hotels'),
31
+ back: async page => await page.click('[aria-label="Close"]'),
32
+ };
33
+ const {leaks} = await run({scenario});
34
+ })();
35
+ ```
36
+
37
+ `action` and `back` receive a Puppeteer
38
+ [`Page`](https://pptr.dev/api/puppeteer.page), so anything Puppeteer can do,
39
+ your scenario can do.
40
+
41
+ ## Take snapshots now, find leaks later
42
+
43
+ `takeSnapshots` runs the browser part only. Pass its result to `findLeaks`
44
+ when you want the leaks:
45
+
46
+ ```javascript
47
+ const {findLeaks, takeSnapshots} = require('@memlab/api');
48
+
49
+ (async function () {
50
+ const scenario = {
51
+ url: () => 'https://www.facebook.com',
52
+ };
53
+ const result = await takeSnapshots({scenario, consoleMode: 'SILENT'});
54
+ const leaks = await findLeaks(result, {consoleMode: 'CONTINUOUS_TEST'});
55
+ })();
56
+ ```
57
+
58
+ ## Find leaks in snapshots taken elsewhere
59
+
60
+ If another tool took the heap snapshots, for example a Playwright or Cypress
61
+ test, pass the three files to memlab directly:
62
+
63
+ ```javascript
64
+ const {SnapshotResultReader, findLeaks} = require('@memlab/api');
65
+
66
+ // baseline, target, and final are paths to .heapsnapshot files
67
+ const reader = SnapshotResultReader.fromSnapshots(baseline, target, final);
68
+ const leaks = await findLeaks(reader);
69
+ ```
70
+
71
+ `findLeaksBySnapshotFilePaths(baseline, target, final)` does the same in one
72
+ call. See
73
+ [Integrate with Test Frameworks](https://meta.github.io/memlab/docs/guides/integrate-with-e2e-frameworks)
74
+ for the files memlab expects.
75
+
76
+ ## Run a heap analysis
77
+
78
+ Every analysis from
79
+ [`@memlab/heap-analysis`](https://www.npmjs.com/package/@memlab/heap-analysis)
80
+ is re-exported here. `analyze` runs one on the snapshots from a run:
81
+
82
+ ```javascript
83
+ const {analyze, takeSnapshots, StringAnalysis} = require('@memlab/api');
84
+
85
+ (async function () {
86
+ const scenario = {
87
+ url: () => 'https://www.facebook.com',
88
+ };
89
+ const result = await takeSnapshots({scenario});
90
+ const analysis = new StringAnalysis();
91
+ await analyze(result, analysis);
92
+ })();
93
+ ```
94
+
95
+ ## Read the results of a run
96
+
97
+ A run writes its heap snapshots, screenshots, browser console output, and
98
+ leak traces to a working directory (set it with the `workDir` option).
99
+ `BrowserInteractionResultReader` reads them back:
100
+
101
+ ```javascript
102
+ const {BrowserInteractionResultReader} = require('@memlab/api');
103
+
104
+ const result = BrowserInteractionResultReader.from('/path/to/work/dir/');
105
+
106
+ // absolute paths of all heap snapshot files
107
+ const files = result.getSnapshotFiles();
108
+
109
+ // everything the page printed to the browser console
110
+ const metaInfo = result.getRunMetaInfo();
111
+ console.log(metaInfo.browserInfo._consoleMessages.join('\n'));
112
+
113
+ // delete the results when you are done
114
+ result.cleanup();
115
+ ```
116
+
117
+ ## Main exports
118
+
119
+ | Export | What it does |
120
+ | --- | --- |
121
+ | `run` | Take snapshots of a scenario and find leaks in one call |
122
+ | `takeSnapshots` | Run a scenario in the browser and save its heap snapshots |
123
+ | `warmupAndTakeSnapshots` | Warm up the app's server first, then take snapshots |
124
+ | `findLeaks` | Find and cluster leaks in the snapshots of a run |
125
+ | `findLeaksBySnapshotFilePaths` | Find leaks in three snapshot files |
126
+ | `analyze` | Run a heap analysis on the snapshots of a run |
127
+ | `BrowserInteractionResultReader`, `SnapshotResultReader` | Read the results of a run from disk |
128
+ | `config`, `takeNodeMinimalHeap`, `dumpNodeHeapSnapshot` | Re-exported from [`@memlab/core`](https://www.npmjs.com/package/@memlab/core) |
129
+
130
+ The full reference is in the
131
+ [API documentation](https://meta.github.io/memlab/docs/api/api/src/).
5
132
 
6
133
  ## Online Resources
134
+
7
135
  * [Official Website and Demo](https://meta.github.io/memlab)
8
136
  * [Documentation](https://meta.github.io/memlab/docs/intro)
137
+ * [Set up Continuous Test](https://meta.github.io/memlab/docs/guides/integration-and-file-structure)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memlab/api",
3
- "version": "2.0.6",
3
+ "version": "2.0.7",
4
4
  "license": "MIT",
5
5
  "description": "memlab API",
6
6
  "author": "Liang Gong <lgong@meta.com>",
@@ -27,9 +27,9 @@
27
27
  "access": "public"
28
28
  },
29
29
  "dependencies": {
30
- "@memlab/core": "^2.0.6",
31
- "@memlab/e2e": "^2.0.6",
32
- "@memlab/heap-analysis": "^2.0.6",
30
+ "@memlab/core": "^2.0.7",
31
+ "@memlab/e2e": "^2.0.7",
32
+ "@memlab/heap-analysis": "^2.0.7",
33
33
  "ansi": "^0.3.1",
34
34
  "babar": "^0.2.0",
35
35
  "chalk": "^4.0.0",