跳到主要内容
版本：23.11.1

贡献

首先，感谢您对 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_BROWSER=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:** - 在 Chrome 上测试 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 request。有关使用 pull request 的更多信息，请参阅 GitHub 帮助。

代码风格​

我们的编码风格在 .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），除非它们是 非常 需要的。

提交消息​

提交消息应遵循 Conventional Commits 格式。

特别是，破坏性更改应在提交消息的页脚中清楚地注明为“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 Actions，每天运行一次。该 Action 有一个手动触发器，可以在Actions 选项卡上找到。

手动说明​

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

注意：您可能需要运行 node --experimental-fetch tools/update_browser_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.json，并使用列表中下一个版本更新 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. 提交并推送您的更改，并打开一个 pull request。提交消息必须包含 Chrome <version> 格式的版本，以确保 pptr.dev 可以正确解析它，例如 feat(chrome): roll to Chrome 90.0.4427.0。

二分查找上游更改​

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

发布到 npm​

我们使用 release-please 来自动化发布。当应该进行发布时，请在我们的pull requests中检查发布 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. 确保该 issue 被标记为 bug 或 feature。
  2. 如果该 issue 没有清晰的重现步骤或者您无法重现，请要求提供重现步骤并设置 needs-feedback 标签。
  3. 跟进您之前要求提供反馈的 issue（当用户回复时，您应该会在 GitHub 上收到通知）。
  4. 如果用户不提供反馈，该 issue 最终会被过时的机器人关闭。
  5. 如果您能够重现该 issue，请添加标签 confirmed。
  6. 如果该错误发生在 Chromium 端，请创建一个相应的 crbug.com issue，使用 upstream 标签标记 GitHub issue，并在评论中发布指向 crbug.com 的链接。
  7. 如果该 issue 与 Puppeteer 或 Chromium 都不相关，请关闭该 issue。
  8. 如果该 issue 与缺少/不正确的文档相关，请将其标记为 documentation。

PDF 的问题

  1. 如果该 issue 使用常规打印对话框和/或 headful 模式重现，请针对 Blink>Layout 组件在 crbug.com 上提交一个 issue。
  2. 如果该 issue 仅在 Headless 模式下出现，请针对 Internals>Headless 组件在 crbug.com 上提交一个 issue。