贡献
¥Contributing
首先感谢你对 Puppeteer 的关注!我们很乐意接受你的补丁和贡献!
¥First of all, thank you for your interest in Puppeteer! We'd love to accept your patches and contributions!
贡献者许可协议
¥Contributor License Agreement
对此项目的贡献必须附有贡献者许可协议。你(或你的雇主)保留你贡献的版权,这只是允许我们使用和重新分发你的贡献作为项目的一部分。前往 <https://cla.developers.google.com/> 查看你当前存档的协议或签署新协议。
¥Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to <https://cla.developers.google.com/> to see your current agreements on file or to sign a new one.
你通常只需要提交一次 CLA,因此如果你已经提交了一份 CLA(即使是针对不同的项目),你可能不需要再次提交。
¥You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
新手入门
¥Getting started
-
克隆这个存储库
¥Clone this repository
git clone https://github.com/puppeteer/puppeteer
cd puppeteer或者
¥or
-
安装依赖
¥Install the dependencies
npm install
# Or to download Firefox by default
PUPPETEER_PRODUCT=firefox npm install -
构建所有包
¥Build all packages
npm run build
-
运行所有测试
¥Run all tests
npm test
构建单个包
¥Building a single package
要构建单个包,你可以运行:
¥To build a single package, you can run:
npm run build --workspace <package> # e.g. puppeteer
这将自动构建所有依赖包,因此指定单个包就足够了。这一切都是可能的,因为 wireit 的行为与 GNU 使 类似。
¥This will build all dependent packages automatically, so specifying a single package is sufficient. This is all possible due to wireit which behaves similar to GNU Make.
监视模式
¥Watch mode
要持续构建包,你可以运行:
¥To continuously build a package, you can run:
npm run build --watch --workspace <package> # e.g. puppeteer
你必须只指定一个包来观察,否则事情将无法按预期工作如上所述,因为 wireit,当发生更改时,所有依赖都将被构建或重建(如果需要)。
¥You have to only specify a single package to watch else things will not work as expected As stated above because of wireit when a change happens all dependencies will be build or rebuild (if needed).
删除旧的工件
¥Removing stale artifacts
某些生成的工件(例如 packages/puppeteer-core/src/types.ts
)可能会变得过时,因为这些工件依赖于构建系统无法捕获的复杂条件(例如不同文件的名称)。要清理工件,你可以运行
¥It's possible some generated artifacts (such as
packages/puppeteer-core/src/types.ts
) can become stale since these artifacts
rely on complex conditions (such as names of distinct files) that cannot be
captured by the build system. To clean artifacts, you can run
npm run clean
# or specify the package
npm run clean --workspace <package>
综合测试
¥Comprehensive testing
除了 npm test
之外,还有其他几个通常通过 CI 检查的 npm
脚本:
¥Outside of npm test
, there are several other
npm
scripts that are
usually check through CI:
-
test-install
- 测试puppeteer
和puppeteer-core
是否安装正确且功能正常。¥
test-install
- Tests whetherpuppeteer
andpuppeteer-core
install properly and are functional. -
test-types
- 使用tsd
测试puppeteer
中的 TypeScript 类型。¥
test-types
- Tests the TypeScript types inpuppeteer
usingtsd
. -
test:chrome:**
- 在 Chromium 上测试puppeteer
。¥
test:chrome:**
- Testspuppeteer
on Chromium. -
test:firefox:**
- 在 Firefox 上测试puppeteer
。¥
test:firefox:**
- Testspuppeteer
on Firefox. -
unit
- 运行单元测试。¥
unit
- Runs unit tests.
默认的 npm test
运行 test:{chrome,firefox}:headless
,这通常就足够了。
¥The default npm test
runs test:{chrome,firefox}:headless
which is generally
sufficient.
Puppeteer 在 Mocha 之上使用自定义测试运行器,该测试运行器咨询 TestExpectations.json 以查看给定的测试结果是否符合预期。请参阅 tools/mocha-runner
中有关测试运行程序的更多信息。
¥Puppeteer uses a custom test runner on top of Mocha that consults the
TestExpectations.json
to see if a given test result is expected or not. See more info about the test
runner in
tools/mocha-runner
.
单元测试
¥Unit tests
仅将测试代码(没有正在运行的浏览器)放置在它们使用 Node 测试运行程序(需要 Node 20+)测试和运行的类旁边的测试:
¥Tests that only test code (without the running browser) are put next to the classes they test and run using the Node test runner (requires Node 20+):
npm run unit
代码审查
¥Code reviews
所有提交的内容,包括项目成员提交的内容,都需要审核。为此,我们使用 GitHub 拉取请求。有关使用拉取请求的更多信息,请参阅 GitHub 帮助。
¥All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.
代码风格
¥Code Style
我们的编码风格在 .eslintrc
(ESLint)和 .prettierrc.cjs
(Prettier)中得到了完整的定义。
¥Our coding style is fully defined in
.eslintrc
(ESLint) and
.prettierrc.cjs
(Prettier).
代码会自动检查 PR,你可以通过运行以下命令手动检查代码:
¥Code is checked for PRs automatically and you can check your code manually by running:
npm run lint
如果返回一些错误,你可以尝试使用以下方法修复它们:
¥If some errors are returned, you can attempt to fix them using:
npm run format
项目结构
¥Project structure
以下是 Puppeteer 中主要文件夹的说明:
¥The following is a description of the primary folders in Puppeteer:
-
packages
包含所有公共源代码。¥
packages
contains all public source code. -
test
包含所有测试源代码。¥
test
contains all test source code. -
test-d
包含使用tsd
的型式测试。¥
test-d
contains type tests usingtsd
. -
tools
包含用于构建等的各种脚本。¥
tools
contains miscellaneous scripts that are used in building and etc. -
tools/mocha-runner
- 包含我们的测试运行程序的源代码。¥
tools/mocha-runner
- contains the source code for our test runner.
API 指南
¥API guidelines
编写新的 API 方法时,请考虑以下事项:
¥When authoring new API methods, consider the following:
-
根据需要公开尽可能少的信息。如有疑问,请勿透露新信息。
¥Expose as little information as needed. When in doubt, don’t expose new information.
-
方法的使用有利于 getter/setter。
¥Methods are used in favor of getters/setters.
-
唯一的例外是命名空间,例如
page.keyboard
和page.coverage
¥The only exception is namespaces, e.g.
page.keyboard
andpage.coverage
-
-
所有字符串字面量都必须是小写字母。这包括事件名称和选项值。
¥All string literals must be small case. This includes event names and option values.
-
避免添加 "sugar" API(可以在用户空间中轻松实现的 API),除非非常需要。
¥Avoid adding "sugar" API (API that is trivially implementable in user-space) unless they're extremely demanded.