@memlab/e2e 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.
package/README.md CHANGED
@@ -1,8 +1,86 @@
1
- ## memlab E2E
1
+ # @memlab/e2e
2
2
 
3
- This is the memlab E2E testing framework for headless/headful Chromium. It is mainly responsible
4
- for controlling/interacting with browser, recording heap snapshots, and logging other execution metadata.
3
+ memlab's browser automation layer. It drives Chromium through
4
+ [Puppeteer](https://pptr.dev/), runs the steps of a test scenario, and records
5
+ what memlab needs to find memory leaks: a JavaScript heap snapshot after each
6
+ step, screenshots, the browser console output, and metadata about the run.
7
+
8
+ You rarely need to depend on this package directly.
9
+ [`memlab run`](https://www.npmjs.com/package/memlab) and
10
+ [`@memlab/api`](https://www.npmjs.com/package/@memlab/api) use it for you. It
11
+ is published separately so the other memlab packages can share it.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @memlab/e2e
17
+ ```
18
+
19
+ ## What a run does
20
+
21
+ For a [test scenario](https://meta.github.io/memlab/docs/api/core/src/interfaces/IScenario)
22
+ with `url`, `action`, and `back` callbacks, the browser run:
23
+
24
+ 1. Launches Chromium, headless by default.
25
+ 2. Calls `beforeInitialPageLoad`, sets `cookies`, and loads the page returned
26
+ by `url`. Then it calls `setup` once. After this and every later step, it
27
+ waits until `isPageLoaded` returns true or, without that callback, until
28
+ the page has had no network connections for 500ms.
29
+ 3. Takes the **baseline** heap snapshot.
30
+ 4. Calls `action`, the interaction you suspect leaks memory, and takes the
31
+ **target** heap snapshot.
32
+ 5. Calls `back` to undo the interaction and takes the **final** heap snapshot.
33
+ With `repeat`, it runs `action` and `back` extra times first.
34
+
35
+ Before each snapshot it runs garbage collection in the page, and on the target
36
+ and final pages it does extra interactions such as scrolling and waiting.
37
+ Comparing the three snapshots finds objects that were allocated by `action`
38
+ but are still alive after `back`. See
39
+ [How memlab Works](https://meta.github.io/memlab/docs/how-memlab-works).
40
+
41
+ ## What it writes
42
+
43
+ Results go to the working directory (`--work-dir`, or
44
+ `memlab get-default-work-dir`):
45
+
46
+ ```
47
+ data/cur/
48
+ ├── s1.heapsnapshot # baseline: after the initial page load
49
+ ├── s2.heapsnapshot # target: after action
50
+ ├── s3.heapsnapshot # final: after back
51
+ ├── screenshot-1.png # one screenshot per step
52
+ ├── ...
53
+ ├── browser-info.txt # browser console output
54
+ ├── run-meta.json # browser and run configuration
55
+ └── snap-seq.json # one entry per interaction step
56
+ ```
57
+
58
+ Another E2E framework, such as Playwright or Cypress, can write these files
59
+ itself and hand them to memlab. See
60
+ [Integrate with Test Frameworks](https://meta.github.io/memlab/docs/guides/integrate-with-e2e-frameworks)
61
+ for the format of `snap-seq.json` and `run-meta.json`.
62
+
63
+ ## Browser options
64
+
65
+ These `memlab run` and `memlab snapshot` options are handled here:
66
+
67
+ | Option | Effect |
68
+ | --- | --- |
69
+ | `--headful` | Show the browser window |
70
+ | `--device <name>` | Emulate a device, for example a phone |
71
+ | `--user-agent <ua>` | Override the browser's user agent |
72
+ | `--chromium-binary <path>` | Use a specific Chromium build |
73
+ | `--full` | Take a heap snapshot after every step, not just the three above |
74
+ | `--skip-gc`, `--skip-scroll`, `--skip-extra-ops`, `--skip-screenshot` | Skip parts of each step to make a run faster |
75
+ | `--display-leak-outlines` | Outline leaked components on the page (with `--headful`), using [`@memlab/lens`](https://www.npmjs.com/package/@memlab/lens) |
76
+ | `--disable-xvfb` | Don't use a virtual display for headful runs on Linux |
77
+ | `--protocol-timeout <ms>` | Allow more time for very large heap snapshots |
78
+
79
+ The full list is in the
80
+ [CLI reference](https://meta.github.io/memlab/docs/cli/run/).
5
81
 
6
82
  ## Online Resources
83
+
7
84
  * [Official Website and Demo](https://meta.github.io/memlab)
8
85
  * [Documentation](https://meta.github.io/memlab/docs/intro)
86
+ * [Test scenario reference](https://meta.github.io/memlab/docs/api/core/src/interfaces/IScenario)
@@ -1 +1 @@
1
- {"version":3,"file":"TestRunnerLoader.d.ts","sourceRoot":"","sources":["../src/TestRunnerLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,iCAAiC,EAAC,MAAM,cAAc,CAAC;AAIpE,cAAM,gBAAgB;IACpB,IAAI,IAAI,iCAAiC,EAAE;CAuB5C;;AAED,wBAAsC"}
1
+ {"version":3,"file":"TestRunnerLoader.d.ts","sourceRoot":"","sources":["../src/TestRunnerLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,iCAAiC,EAAC,MAAM,cAAc,CAAC;AAMpE,cAAM,gBAAgB;IACpB,IAAI,IAAI,iCAAiC,EAAE;CAyB5C;;AAED,wBAAsC"}
@@ -15,6 +15,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
15
15
  const path_1 = __importDefault(require("path"));
16
16
  const core_1 = require("@memlab/core");
17
17
  const BaseSynthesizer_1 = __importDefault(require("./BaseSynthesizer"));
18
+ const DefaultScenarioSynthesizer_1 = __importDefault(require("./plugins/DefaultScenarioSynthesizer"));
19
+ const TestSPAVisitSynthesizer_1 = __importDefault(require("./plugins/TestSPAVisitSynthesizer"));
18
20
  class TestRunnerLoader {
19
21
  load() {
20
22
  const ret = [];
@@ -35,7 +37,9 @@ class TestRunnerLoader {
35
37
  }
36
38
  ret.push(constructor);
37
39
  });
38
- return ret;
40
+ return ret.length > 0
41
+ ? ret
42
+ : [DefaultScenarioSynthesizer_1.default, TestSPAVisitSynthesizer_1.default];
39
43
  }
40
44
  }
41
45
  exports.default = new TestRunnerLoader();
@@ -1 +1 @@
1
- {"version":3,"file":"Script.d.ts","sourceRoot":"","sources":["../../src/code-analysis/Script.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAW,QAAQ,EAAC,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAQV,cAAc,EACf,MAAM,cAAc,CAAC;AAQtB,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4BAA4B,EAAE,MAAM,EAAE,CAAC;IACvC,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B,GAAG,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CAC/B,CAAC;AAmBF,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,gBAAgB,CAAe;gBAE3B,IAAI,EAAE,MAAM;IAOjB,mBAAmB,IAAI,YAAY;IAI1C,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,8BAA8B;IAiBtC,OAAO,CAAC,qBAAqB;CA+F9B"}
1
+ {"version":3,"file":"Script.d.ts","sourceRoot":"","sources":["../../src/code-analysis/Script.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAW,QAAQ,EAAC,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAQV,cAAc,EACf,MAAM,cAAc,CAAC;AAQtB,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4BAA4B,EAAE,MAAM,EAAE,CAAC;IACvC,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B,GAAG,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CAC/B,CAAC;AAmBF,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,OAAO,CAAC,GAAG,CAAwB;IACnC,OAAO,CAAC,gBAAgB,CAAe;gBAE3B,IAAI,EAAE,MAAM;IAOjB,mBAAmB,IAAI,YAAY;IAI1C,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,8BAA8B;IAiBtC,OAAO,CAAC,qBAAqB;CA0F9B"}
@@ -74,10 +74,8 @@ class Script {
74
74
  };
75
75
  const locToClosureScopeMap = new Map();
76
76
  locToClosureScopeMap.set(this.locToStr(ast.program.loc), root);
77
- // eslint-disable-next-line @typescript-eslint/no-this-alias
78
- const self = this;
79
77
  // build closure scope hierarchy
80
- const buildClosureScopeFromFunction = function (path) {
78
+ const buildClosureScopeFromFunction = (path) => {
81
79
  var _a, _b;
82
80
  const closureScope = {
83
81
  functionName: 'id' in path.node ? (_b = (_a = path.node) === null || _a === void 0 ? void 0 : _a.id) === null || _b === void 0 ? void 0 : _b.name : null,
@@ -87,9 +85,9 @@ class Script {
87
85
  nestedClosures: [],
88
86
  loc: path.node.loc,
89
87
  };
90
- locToClosureScopeMap.set(self.locToStr(path.node.loc), closureScope);
88
+ locToClosureScopeMap.set(this.locToStr(path.node.loc), closureScope);
91
89
  // find and connect to parent closure scope
92
- const parentClosureScope = self.findParentFunctionClosureScope(locToClosureScopeMap, path);
90
+ const parentClosureScope = this.findParentFunctionClosureScope(locToClosureScopeMap, path);
93
91
  parentClosureScope.nestedClosures.push(closureScope);
94
92
  };
95
93
  // Traverse the parent scope of the containing scope
@@ -99,26 +97,26 @@ class Script {
99
97
  // of the containing scope
100
98
  // If true, add the identifier name to the usedVariablesFromParentScope
101
99
  // of the containing scope
102
- const fillInVarInfo = function (path) {
100
+ const fillInVarInfo = (path) => {
103
101
  // if the identifier is a function name of a function definition
104
102
  if (isFunctionType(path.parentPath.node.type)) {
105
103
  return;
106
104
  }
107
105
  const name = path.node.name;
108
- let parentPath = self.findParentFunctionPath(path);
106
+ let parentPath = this.findParentFunctionPath(path);
109
107
  let parentClosureScope = parentPath
110
- ? locToClosureScopeMap.get(self.locToStr(parentPath.node.loc))
108
+ ? locToClosureScopeMap.get(this.locToStr(parentPath.node.loc))
111
109
  : null;
112
110
  // eslint-disable-next-line no-constant-condition
113
111
  while (true) {
114
112
  if (!parentPath || !parentClosureScope) {
115
113
  break;
116
114
  }
117
- const grandparentPath = self.findParentFunctionPath(parentPath);
115
+ const grandparentPath = this.findParentFunctionPath(parentPath);
118
116
  if (!grandparentPath) {
119
117
  break;
120
118
  }
121
- const grandparentClosureScope = locToClosureScopeMap.get(self.locToStr(grandparentPath.node.loc));
119
+ const grandparentClosureScope = locToClosureScopeMap.get(this.locToStr(grandparentPath.node.loc));
122
120
  if (!grandparentClosureScope) {
123
121
  break;
124
122
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memlab/e2e",
3
- "version": "2.0.6",
3
+ "version": "2.0.7",
4
4
  "license": "MIT",
5
5
  "description": "memlab browser E2E interaction libraries",
6
6
  "author": "Liang Gong <lgong@meta.com>",
@@ -25,8 +25,8 @@
25
25
  "@babel/parser": "^7.16.4",
26
26
  "@babel/template": "^7.16.0",
27
27
  "@babel/traverse": "^7.16.3",
28
- "@memlab/core": "^2.0.6",
29
- "@memlab/lens": "^2.0.6",
28
+ "@memlab/core": "^2.0.7",
29
+ "@memlab/lens": "^2.0.7",
30
30
  "ansi": "^0.3.1",
31
31
  "babar": "^0.2.0",
32
32
  "chalk": "^4.0.0",