常见问题解答

跨浏览器支持处于什么状态？

Firefox 官方支持功能尚处于实验阶段。我们将与 Mozilla 进行持续协作，为常见的端到端测试用例提供支持，在这类用例中，开发者希望能够实现跨浏览器测试。Puppeteer 团队需要用户提供意见，以稳定对 Firefox 的支持，并提醒我们关注缺失的 API。

从 Puppeteer v2.1.0 开始，您可以指定 puppeteer.launch({product: 'firefox'}) 在 Firefox Nightly 中运行 Puppeteer 脚本，而无需任何其他自定义
补丁。虽然旧版实验需要使用 Firefox 的修补版本，但当前的方法适用于“stock”Firefox。

我们会继续与其他浏览器供应商合作，为 Safari 等浏览器引入 Puppeteer 支持。这项工作包括探索用于执行跨浏览器命令的标准（而不是依赖于 Chrome 使用的非标准开发者工具协议）。

Puppeteer 的目标和原则是什么？

该项目的目标是：

  • 提供一个精简的规范库，凸显 DevTools 协议的功能。
  • 为类似测试库提供参考实现。最终，这些其他框架可以采用 Puppeteer 作为基础层。
  • 增加无头/自动浏览器测试的采用率。
  • 帮助 dogfood 新的开发者工具协议功能...以及发现错误！
  • 详细了解自动化浏览器测试的痛点，并帮助填补这些缺口。

我们调整 Chromium 原则来帮助做出产品决策：

  • 速度：在自动化网页上，Puppeteer 的性能开销几乎为零。
  • 安全性：Puppeteer 对 Chromium 运行离线进程，因此可以安全地自动运行潜在的恶意网页。
  • 稳定性：Puppeteer 不应该不稳定，不应泄漏内存。
  • 简单性：Puppeteer 提供易于使用、理解和调试的高级别 API。

Puppeteer 是否会取代 Selenium/WebDriver？

否。这两个项目都有其价值，原因截然不同：

  • Selenium/WebDriver 专注于跨浏览器自动化；其价值主张是一个适用于所有主流浏览器的标准 API。
  • Puppeteer 专注于 Chromium；其价值主张是更丰富的功能和更高的可靠性。

也就是说，您可以使用 Puppeteer 针对 Chromium 运行测试，例如使用社区驱动的 jest-puppeteer。虽然这可能不是您唯一的测试解决方案，但与 WebDriver 相比，它有几点优势：

  • Puppeteer 需要进行零设置，并且捆绑了最适合使用的 Chromium 版本。最好进行几项仅运行 Chromium 的测试，而不是不运行任何测试。
  • Puppeteer 采用事件驱动型架构，消除了很多潜在不稳定问题。Puppeteer 脚本中无需邪恶的“sleep(1000)”调用。
  • Puppeteer 默认在无头模式下运行，因此可以快速运行。Puppeteer v1.5.0 还公开了浏览器上下文，从而可以高效地并行运行测试作业。
  • Puppeteer 在调试方面表现出色：将“无头”位切换为 false，添加“slowMo”，您就会看到浏览器在做什么。您甚至可以打开 Chrome 开发者工具来检查测试环境。

为什么 Puppeteer v.XXX 无法与 Chromium v.YYY 配合使用？

我们将 Puppeteer 视为 Chromium 中的一个不可分割的实体。Puppeteer 的每个版本都捆绑特定版本的 Chromium，这是保证支持该版本的唯一版本。

这并非人为的约束。关于 Puppeteer 的大部分工作实际上是在 Chromium 代码库中进行。下面是一个典型的故事：

  1. 报告了一个 Puppeteer bug
  2. 这是开发者工具协议存在的问题，因此我们在 Chromium 中解决此问题
  3. 上游修复程序推出后，我们会将更新后的 Chromium 滚动到 Puppeteer

不过，通常情况下，最好将 Puppeteer 与官方 Google Chrome（而非 Chromium）搭配使用。为此，您应安装与 Chrome 版本对应的 puppeteer-core 版本。

例如，如需通过 puppeteer-core 驱动 Chrome 101，请使用 chrome-101 npm 标记：

npm install puppeteer-core@chrome-101

Puppeteer 使用哪个 Chromium 版本？

通过以下某种方式查找版本：

  • 在 revisions.ts 中查找 chromium 条目。如需查找相应的 Chromium 提交内容和版本号，请在 OmahaProxy 的“Find Releases”部分中搜索以 r 为前缀的修订版本。
  • 您可以在 versions.js 中查找 versionsPerRelease 映射，其中包含 Chromium 和 Puppeteer 版本之间的映射。注意：此文件仅包含更新了 Chromium 的 Puppeteer 版本。并未列出所有 Puppeteer 版本。

Puppeteer 使用哪个 Firefox 版本？

由于 Firefox 支持尚处于实验阶段，因此当 PUPPETEER_PRODUCT 环境变量设置为 firefox 时，Puppeteer 会下载最新的 Firefox Nightly。这也是 revisions.ts 中 firefox 的值为 latest 的原因，即 Puppeteer 未与特定的 Firefox 版本关联。

如需在安装 Puppeteer 的过程中提取 Firefox Nightly，请执行以下操作：

PUPPETEER_PRODUCT=firefox npm i puppeteer
# or "yarn add puppeteer"

什么是导航？

从 Puppeteer 的角度来看，“navigation”是指会更改页面网址的任何要素。除了常规导航（即浏览器连接到网络以从网络服务器提取新文档）之外，这包括锚点导航和 History API 用法。

根据“导航”的这种定义，Puppeteer 可与单页应用无缝协作。

“可信”和“不可信”输入事件有何区别？

在浏览器中，输入事件可分为两大类：可信和不可信。

  • 可信事件：用户与网页互动（例如使用鼠标或键盘）生成的事件。
  • 不可信事件：Web API（如 document.createEvent 或 element.click() 方法）生成的事件。

网站可以区分这两类用户：

  • 使用 Event.isTrusted 事件标志
  • 用于嗅探相关事件。例如，每个可信 'click' 事件都以 'mousedown' 和 'mouseup' 事件开头。

为实现自动化，请务必生成可信事件。使用 Puppeteer 生成的所有输入事件都可信，可以触发适当的附带事件。

如果出于某种原因，需要不可信事件，那么始终有可能使用 page.evaluate 进入页面上下文并生成虚假事件：

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

Puppeteer 不支持哪些功能？

您可能会发现，在控制包含音频和视频的网页时，Puppeteer 无法按预期运行。例如，视频播放和屏幕截图可能会失败。）这有两个原因：

  • Puppeteer 与 Chromium（而非 Chrome）捆绑在一起。因此，默认情况下，它继承了 Chromium 的所有媒体相关限制。这意味着 Puppeteer 不支持 AAC 或 H.264 等许可格式。
    • 可以通过 puppeteer.launch 的 executablePath 选项强制 Puppeteer 使用单独安装的版本 Chrome，而不是 Chromium。仅当您需要支持这些媒体格式的 Chrome 正式版本时，才应使用此配置。
  • 由于 Puppeteer（在所有配置中）控制的是桌面版 Chromium 或 Chrome，因此仅支持移动版 Chrome 的功能不受支持。这意味着 Puppeteer 不支持 HTTP Live Streaming (HLS)。

我在测试环境中安装 / 运行 Puppeteer 时遇到问题。我应该在哪里寻求帮助？

我们针对各种操作系统提供了问题排查指南，其中列出了所需的依赖项。

系统每次运行 npm ci 时都会下载 Chromium。如何缓存下载内容？

默认下载路径为 node_modules/puppeteer/.local-chromium。不过，您可以使用 PUPPETEER_DOWNLOAD_PATH 环境变量更改该路径。

在启动期间，Puppeteer 使用该变量来解析 Chromium 可执行文件位置，因此您无需同时指定 PUPPETEER_EXECUTABLE_PATH。

例如，若要将 Chromium 下载内容保留在 ~/.npm/chromium 中，请执行以下命令：

export PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium
npm ci

# by default the Chromium executable path is inferred
# from the download path
npm test

# a new run of npm ci will check for the existence of
# Chromium in ~/.npm/chromium
npm ci

我还有其他问题！我要在哪里询问？

您可以通过多种方式获得有关 Puppeteer 的帮助：

请务必先搜索这些频道，然后再发布问题。