与测试框架集成

本指南介绍如何将 MemLab 与其他现有的 E2E 测试框架（例如 Playwright 或 Cypress）集成。

MemLab 使用 Puppeteer 与 Web 浏览器交互，并收集 JavaScript 堆快照以进行内存泄漏检测。如果您的组织已经使用其他 E2E 测试框架（例如 Playwright 或 Cypress），您可能希望重用现有的框架进行 E2E 测试，并将中间结果传输到 MemLab 以进行内存泄漏检测。

获取 MemLab 可消耗的文件

对于您现有的 E2E 测试框架，您需要实现一个 API，该 API 从浏览器获取 JS 堆快照。（例如，Playwright 支持通过 Chrome DevTools 协议连接浏览器的 DevTools (链接)。因此，您可以利用它从 Chromium 获取 JS 堆快照。这是 memlab 如何使用 puppeteer 从 Chromium 收集堆快照的代码指针。

API 可能如下所示（例如）

await takeJSHeapSnapshot(page, tag);

tag 是以下标签之一：baseline、target、final，这三个快照分别等效于 SBP、STP、SBP'。

您的 takeJSHeapSnapshot API 应该以特定格式在磁盘上转储文件。这是 MemLab 核心 API 查找内存泄漏所需的文件和目录结构的完整列表。

/path/to/dump/
└── data
    └── cur
        ├── run-meta.json       # (optional) meta data of memlab run and browser configuration
        ├── s1.heapsnapshot     # heap snapshot after the url callback (initial page load)
        ├── s2.heapsnapshot     # heap snapshot after the action callback (after target interaction)
        ├── s3.heapsnapshot     # heap snapshot after the back callback (after reverting target interaction)
        └── snap-seq.json       # meta data about each browser interaction step

要获取这些元文件的示例，请运行随机 MemLab 测试场景，并在以下目录中查看这些文件：$(memlab get-default-work-dir)/data/cur

在您特定测试框架的测试代码中，您可以在您的 playwright 测试代码中插入这些 takeJSHeapSnapshot API 调用，以收集三个快照并将文件转储到磁盘上。

将文件导入 MemLab

一旦您有了 takeJSHeapSnapshot 实现，将堆快照和元文件转储到磁盘上，您可以使用这个 memlab 核心 API 查找内存泄漏

const {findLeaks, BrowserInteractionResultReader} = require('@memlab/api');

(async function () {
  const reader = BrowserInteractionResultReader.from('/path/to/dump/');
  const leaks = await findLeaks(reader);
})();

`snap-seq.json` 的规范

snap-seq.json 文件编码了浏览器交互数据和堆快照详细信息，Memlab 泄漏检测器需要这些信息来识别内存泄漏。

这是一个示例 snap-seq.json 文件。这是一个数组，其中包含一系列对象，每个对象代表一个浏览器交互步骤。为了检测内存泄漏，我们至少需要按顺序标记为 baseline、target 和 final 的三个步骤。有关 Memlab 为何需要三个快照的详细理解，请参阅此文档。

[
  {
    "name": "page-load",
    "snapshot": true,
    "type": "baseline",
    "idx": 1,
    "JSHeapUsedSize": 33872820
  },
  {
    "name": "action-on-page",
    "snapshot": true,
    "type": "target",
    "idx": 2,
    "JSHeapUsedSize": 44172336
  },
  {
    "name": "revert",
    "snapshot": true,
    "type": "final",
    "idx": 3,
    "JSHeapUsedSize": 43304156
  }
]

现在让我们看一下特定步骤的 JSON 编码

{
  "name": "page-load",
  "snapshot": true,
  "type": "baseline",
  "idx": 1,
  "JSHeapUsedSize": 33872820
}

name 是交互步骤的易读名称，这主要用于文档或注释目的。
"snapshot": true 表示在此 E2E 交互步骤之后已捕获堆快照。如果此字段为 false，则 Memlab 在加载和比较堆快照时将忽略此 E2E 交互步骤。
type 应该是以下值之一：baseline、target 或 final。有关其含义，请参阅此链接。
idx 表示给定交互的索引。当 snapshot 为 true 时，Memlab 利用此索引使用模板 s${idx}.heapsnapshot 来识别和加载相应的堆快照。例如，在这种特定情况下，鉴于 idx 为 1，Memlab 将尝试在与 snap-seq.json 文件相同的目录中查找 s1.heapsnapshot。
JSHeapUsedSize 是一个可选字段，用于记录此 E2E 交互步骤完成后以字节为单位的总堆大小。如果所有交互步骤都包含 JSHeapUsedSize 字段，则 Memlab 将生成一个像素图，显示不同步骤之间的内存使用情况变化，然后在终端上列出检测到的内存泄漏。

`run-meta.json` 的规范（可选）

run-meta.json 文件是 Memlab 的 E2E 前端创建的可选 JSON 文件。您可以选择使您的 E2E 测试框架生成这样的文件。它记录与 Memlab 操作相关的元数据，包括 Chromium 启动参数、有关被测 Web 应用程序的信息以及任何 CLI 命令。虽然此文件在 Memlab 的内存泄漏检测过程中不会直接使用，但稍后对于将检测到的内存泄漏与被测 Web 应用程序和浏览器的配置相关联可能很有价值。例如，有时内存泄漏仅在特定配置（例如移动视图）中显示。当您构建 UI 系统来显示所有内存泄漏及其底层应用程序和浏览器信息时，这些信息可能会很有用。

{
  "app": "default-app-for-scenario",
  "type": "scenario",
  "interaction": "test-google-maps.js",
  "browserInfo": {
    "_browserVersion": "HeadlessChrome/101.0.4950.0",
    "_puppeteerConfig": {
      "headless": true,
      "devtools": true,
      "userDataDir": "/tmp/memlab/data/profile",
      "args": [
        "--no-sandbox",
        "--disable-notifications",
        "--use-fake-ui-for-media-stream",
        "--use-fake-device-for-media-stream",
        "--js-flags=\"--no-move-object-start\"",
        "--enable-precise-memory-info",
        "browser-test",
        "--display=:100"
      ],
      "defaultViewport": {
        "width": 1680,
        "height": 1080,
        "deviceScaleFactor": 1
      }
    },
    "_consoleMessages": [
      "console output line 1",
      "console output line 2",
    ]
  },
  "extraInfo": {
    "command": "run --scenario /home/jacksongl/scripts/test-google-maps.js"
  }
}

所有这些字段都是可选的

app：指定应用程序的名称，在本例中为“default-app-for-scenario”。
type：描述测试的类型，这里是“scenario”。
interaction：E2E 测试场景文件的文件名。
browserInfo：包含有关用于测试的浏览器的元数据
- _browserVersion：使用的浏览器的版本，例如，HeadlessChrome/101.0.4950.0。
- _puppeteerConfig：Puppeteer 的配置（MemLab 使用 Puppeteer 作为其浏览器交互前端）
  - headless：一个布尔值，指示浏览器是否在无头模式下运行。
  - devtools：一个布尔值，指定与页面交互时是否打开 devtools。
  - userDataDir：浏览器生成的测试用户配置文件数据目录的路径。
  - args：要传递给浏览器实例的附加参数的数组。
  - defaultViewport：一个对象，指定默认视口的宽度、高度和设备比例因子。
- _consoleMessages：测试运行期间在控制台中输出的消息数组。
extraInfo：包含有关测试运行的其他信息
- command：用于启动测试运行的命令，在本例中为 memlab run --scenario /home/jacksongl/scripts/test-google-maps.js。

讨论

如有问题和讨论，请查看 issue #35、#15 和 #14。

与测试框架集成

获取 MemLab 可消耗的文件​

将文件导入 MemLab​

snap-seq.json 的规范​

run-meta.json 的规范（可选）​

讨论​

获取 MemLab 可消耗的文件

将文件导入 MemLab

`snap-seq.json` 的规范

`run-meta.json` 的规范（可选）

讨论