跳至主要內容
版本：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）。

提交訊息​

提交訊息應遵循 慣例式提交格式。

特別是，重大變更應在提交訊息的頁尾中清楚地註明為「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 標籤上找到。

手動說明​

您可以本地執行 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. 提交並推送您的變更，並開啟一個拉取請求。提交訊息必須包含 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 來自動化發佈。當應該進行發佈時，請在我們的 拉取請求中檢查發佈 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 問題，使用 upstream 標籤標記 GitHub 問題，並在評論中貼上 crbug.com 的連結。
  7. 如果問題與 Puppeteer 或 Chromium 無關，請關閉該問題。
  8. 如果問題是關於遺失/不正確的文檔，請將其標記為 documentation。

PDF 問題

  1. 如果問題使用常規列印對話框和/或 headful 模式重現，請在 crbug.com 上針對 Blink>Layout 元件提交問題。
  2. 如果問題特定於 Headless 模式，請在 crbug.com 上針對 Internals>Headless 元件提交問題。