跳至主要内容
版本：22.5.0

贡献

首先，感谢您对 Puppeteer 的兴趣！我们很乐意接受您的补丁和贡献！

贡献者许可协议​

对本项目的贡献必须附带贡献者许可协议。您（或您的雇主）保留对您贡献的版权，这只是允许我们作为项目的一部分使用和重新分发您的贡献。前往 <https://cla.developers.google.com/> 查看您当前的协议文件或签署新的协议。

您通常只需要提交一次 CLA，因此如果您已经提交过（即使是针对不同的项目），您可能不需要再次提交。

入门​

  1. 克隆此仓库

    git clone https://github.com/puppeteer/puppeteer
    cd puppeteer

    或者

    Open in GitHub Codespaces

  2. 安装依赖项

    npm install
    # Or to download Firefox by default
    PUPPETEER_PRODUCT=firefox npm install

  3. 构建所有包

    npm run build

  4. 运行所有测试

    npm test

构建单个包​

要构建单个包，您可以运行

npm run build --workspace <package> # e.g. puppeteer

这将自动构建所有依赖包，因此指定单个包就足够了。这得益于 wireit，它的行为类似于 GNU Make。

观察模式​

要持续构建一个包，您可以运行

npm run build --watch --workspace <package> # e.g. puppeteer

您只需要指定一个要观察的包，否则由于 wireit 的原因，事情将无法按预期工作，当发生更改时，所有依赖项将被构建或重建（如果需要）。

删除陈旧的工件​

一些生成的工件（例如 packages/puppeteer-core/src/types.ts）可能会变得陈旧，因为这些工件依赖于复杂的条件（例如不同文件的名称），而这些条件无法被构建系统捕获。要清理工件，您可以运行

npm run clean
# or specify the package
npm run clean --workspace <package>

全面测试​

除了 npm test 之外，还有其他几个 npm 脚本 通常通过 CI 检查

  • test-install - 测试 puppeteer 和 puppeteer-core 是否正确安装并正常工作。
  • test-types - 使用 tsd 测试 puppeteer 中的 TypeScript 类型。
  • test:chrome:** - 在 Chromium 上测试 puppeteer。
  • test:firefox:** - 在 Firefox 上测试 puppeteer。
  • unit - 运行单元测试。

默认的 npm test 运行 test:{chrome,firefox}:headless，这通常就足够了。

Puppeteer 在 Mocha 之上使用自定义测试运行器，该运行器会查询 TestExpectations.json 以查看给定测试结果是否预期结果。有关测试运行器的更多信息，请参见 tools/mocha-runner。

单元测试​

仅测试代码（不运行浏览器）的测试放在它们测试的类旁边，并使用 Node 测试运行器运行（需要 Node 20+）

npm run unit

代码审查​

所有提交，包括项目成员的提交，都需要审查。我们使用 GitHub pull requests 来完成此目的。请参阅 GitHub 帮助 以获取有关使用 pull requests 的更多信息。

代码风格​

我们的代码风格在 .eslintrc (ESLint) 和 .prettierrc.cjs (Prettier) 中完全定义。

代码会自动检查 PR，您也可以通过运行以下命令手动检查代码

npm run lint

如果返回一些错误，您可以尝试使用以下命令修复它们

npm run format

项目结构​

以下是 Puppeteer 中主要文件夹的描述

  • packages 包含所有公共源代码。
  • test 包含所有测试源代码。
  • test-d 使用 tsd 包含类型测试。
  • tools 包含用于构建等的各种脚本。
  • tools/mocha-runner - 包含我们测试运行器的源代码。

API 指南​

在编写新的 API 方法时，请考虑以下事项

  • 仅公开必要的信息。如有疑问，请勿公开新信息。
  • 优先使用方法而不是 getter/setter。
    • 唯一的例外是命名空间，例如 page.keyboard 和 page.coverage
  • 所有字符串文字必须是小写。这包括事件名称和选项值。
  • 避免添加“糖”API（在用户空间中可以轻松实现的 API），除非它们是 **非常** 需要。

提交信息​

提交信息应遵循 常规提交格式。

特别是，重大更改应在提交信息页脚中明确标注为“BREAKING CHANGE:”。示例

fix(page): fix page.pizza method

This patch fixes page.pizza so that it works with iframes.

Issues: #123, #234

BREAKING CHANGE: page.pizza now delivers pizza at home by default.
To deliver to a different location, use the "deliver" option:
  `page.pizza({deliver: 'work'})`.

编写文档​

文档是通过 npm run docs 从 TSDoc 注释生成的。它会在合并时自动发布到我们的文档网站，并在发布时进行版本控制。

这意味着您不应该手动更改文件 docs/api 中的 markdown。

编写 TSDoc 注释​

Puppeteer 的每次更改都应使用 TSDoc 注释进行详细记录。有关确切语法的详细信息，请参阅 API Extractor 文档。

  • 每个新方法都需要添加 @public 或 @internal 作为标签，具体取决于它是否是公共 API 的一部分。
  • 将注释中的每一行保持在 90 个字符以内（如果超过此限制，ESLint 会发出警告）。如果您是 VSCode 用户，强烈建议使用 Rewrap 插件！

在本地运行文档网站​

  1. 在根目录中，使用 npm i --ignore-scripts 安装所有依赖项。
  2. 运行 npm run docs，这将生成 puppeteer/docs/api 上的所有 .md 文件。
  3. 在 puppeteer/website 中运行 npm i。
  4. 在 puppeteer/website 中运行 npm start。

添加新的依赖项​

对于所有依赖项（包括安装和开发）

  • 不要添加如果所需功能易于实现的依赖项。
  • 如果添加依赖项，它应该维护良好且值得信赖。

引入新的安装依赖项的障碍尤其高

  • 不要添加安装依赖项，除非它对项目成功至关重要。

对于与环境无关的依赖项，还有其他注意事项。有关详细信息，请参阅 third_party/README.md。

测试技巧​

  • 每个功能都应该有相应的测试。
  • 每个公共 API 事件/方法都应该有对应的测试。
  • 测试不应该依赖外部服务。
  • 测试应该在所有三个平台上运行：Mac、Linux 和 Win。这对于截图测试尤其重要。

如果某个测试预计在特定配置下会失败或变得不稳定，请更新 TestExpectations.json 以反映这一点。有关 TestExpectations.json 的更多信息，请参阅 tools/mocha-runner。

API 覆盖率​

每个公共 API 方法或事件都应该在测试中至少调用一次。为了确保这一点，主 test 命令在测试期间运行覆盖率。

调试 Puppeteer​

请参阅 调试技巧。

通过 VSCode 调试 Puppeteer 测试​

将提供的默认 .vscode/launch.template.json 复制到 .vscode/launch.json，然后使用集成的 VSCode 调试器调试测试。

请记住在启动之前通过以下方式构建测试

npm run build --workspace @puppeteer-test/test

面向项目维护者

滚动新的 Chrome 版本​

有一个 GitHub 操作 每天运行一次。该操作有一个手动触发器，可以在 操作选项卡 中找到。

手动说明​

您可以在本地运行 tools/update_chrome_revision.mjs 并尝试查看是否需要提交任何更改。

注意：您可能需要运行 node --experimental-fetch tools/update_chrome_revision.mjs，因为该脚本依赖于 fetch

以下步骤是上面脚本的手动版本。

  1. 通过 https://googlechromelabs.github.io/chrome-for-testing/ 或 https://chromiumdash.appspot.com/ 找到合适的 Chrome revision 和 version。
  2. 使用找到的 version 号更新 packages/puppeteer-core/src/revisions.ts。
  3. 使用新的 Chrome 到 Puppeteer 的 version 映射更新 versions.js，并使用列表中的下一个版本更新 lastMaintainedChromeVersion。
  4. 运行 npm run check。如果失败，请使用预期的 devtools-protocol 版本更新 packages/puppeteer-core/package.json，并运行 npm install 生成更新的 package-lock.json。
  5. 运行 npm run clean、npm install 和 npm run build。
  6. 运行 npm test 并确保所有测试都通过。如果测试失败，请 二分查找 上游故障原因，并根据情况更新测试预期（如果这是预期更改），或者在 Puppeteer 中解决更改（如果不想更改 Puppeteer 的可观察行为）。
  7. 提交并推送您的更改，并打开一个拉取请求。提交消息必须包含 Chrome <version> (r<revision>) 格式的版本，以确保 pptr.dev 可以正确解析它，例如 feat(chrome): roll to Chrome 90.0.4427.0 (r856583)。

注意：您还可以通过在 omahaproxy.appspot.com 的 Find Releases 中搜索 r<revision> 来找到与版本对应的版本。

二分查找上游更改​

要二分查找 Chrome/Chromium 更改，请使用 https://www.chromium.org/developers/bisect-builds-py/.

发布到 npm​

我们使用 release-please 自动化发布。当需要发布时，请检查我们 拉取请求 中的发布 PR 并合并它。

如果 Release Please 失败​

如果 release-please 失败，则需要执行以下操作

  1. 更新所有应该发布的包的 CHANGELOG 中缺少的任何内容。例如，如果标题丢失，您可能需要添加

    • 对于 puppeteer

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/v{PREVIOUS_VERSION}...v{NEW_VERSION}) ({CURRENT_DATE})`

    • 对于其他包

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/{PACKAGE_FOLDER_NAME}-v{PREVIOUS_VERSION}...{PACKAGE_FOLDER_NAME}-v{NEW_VERSION}) ({CURRENT_DATE})

  2. 为每个包创建一个 GitHub 版本，遵循之前版本的做法。

错误分类指南​

查看新进来的错误报告，这些报告没有 confirmed 或 needs-feedback 标签。

  1. 确保问题被标记为 bug 或 feature。
  2. 如果问题没有清晰的复现步骤，或者你无法复现，请要求提供复现步骤并设置 needs-feedback 标签。
  3. 跟进你之前要求反馈的问题（当用户回复时，你应该会收到 GitHub 的通知）。
  4. 如果用户没有提供反馈，问题最终将被过期机器人关闭。
  5. 如果你能够复现问题，请添加 confirmed 标签。
  6. 如果错误在 Chromium 方面，请创建一个相应的 crbug.com 问题，在 GitHub 问题中添加 upstream 标签，并在评论中发布 crbug.com 的链接。
  7. 如果问题与 Puppeteer 或 Chromium 无关，请关闭问题。
  8. 如果问题是关于缺少/错误的文档，请将其标记为 documentation。

PDF 相关问题

  1. 如果问题使用常规打印对话框和/或有头模式可以复现，请在 crbug.com 上针对 Blink>Layout 组件提交问题。
  2. 如果问题是无头模式特有的，请在 crbug.com 上针对 Internals>Headless 组件提交问题。