@memlab/api 2.0.5 → 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.
- package/README.md +134 -5
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,8 +1,137 @@
|
|
|
1
|
-
|
|
1
|
+
# @memlab/api
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
|
7
|
-
|
|
8
|
-
* [
|
|
134
|
+
|
|
135
|
+
* [Official Website and Demo](https://meta.github.io/memlab)
|
|
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.
|
|
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.
|
|
31
|
-
"@memlab/e2e": "^2.0.
|
|
32
|
-
"@memlab/heap-analysis": "^2.0.
|
|
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",
|
|
@@ -52,7 +52,7 @@
|
|
|
52
52
|
},
|
|
53
53
|
"repository": {
|
|
54
54
|
"type": "git",
|
|
55
|
-
"url": "git+https://github.com/
|
|
55
|
+
"url": "git+https://github.com/meta/memlab.git",
|
|
56
56
|
"directory": "packages/api"
|
|
57
57
|
},
|
|
58
58
|
"scripts": {
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
|
|
63
63
|
},
|
|
64
64
|
"bugs": {
|
|
65
|
-
"url": "https://github.com/
|
|
65
|
+
"url": "https://github.com/meta/memlab/issues"
|
|
66
66
|
},
|
|
67
|
-
"homepage": "https://github.com/
|
|
67
|
+
"homepage": "https://github.com/meta/memlab#readme"
|
|
68
68
|
}
|