常見問題

跨瀏覽器支援的狀態為何？

Firefox 官方支援實驗階段。與 Mozilla 持續合作，目標是支援常見的端對端測試使用情境，因為開發人員會預期跨瀏覽器測試。Puppeteer 團隊需要使用者輸入內容，才能穩定 Firefox 支援，並回報缺少的 API。

從 Puppeteer 2.1.0 以上版本，您可以指定 puppeteer.launch({product: 'firefox'}) 在 Firefox Nightly 中執行 Puppeteer 指令碼，而無需任何其他自訂的
修補程式。雖然舊版實驗必須使用 Firefox 修補版本，但目前方法支援「stock」Firefox。

我們會持續與其他瀏覽器供應商合作，讓 Puppeteer 對瀏覽器 (例如 Safari) 的支援。這項工作包括探索執行跨瀏覽器指令的標準 (而非依賴 Chrome 所使用的非標準開發人員工具通訊協定)。

Puppeteer 的目標和原則為何？

這項專案的目標為：

  • 提供精簡的標準程式庫，重點介紹開發人員工具通訊協定的功能。
  • 為類似的測試程式庫提供參考實作。這些其他架構最終可採用 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 採用事件導向架構，可以移除許多潛在的不穩定性。玩偶劇本也不需要邪惡的「sleep(1000)」來電。
  • Puppeteer 預設執行無頭模式，因此運作速度很快。Puppeteer 1.5.0 版也會公開瀏覽器內容，以便有效率地平行處理測試執行作業。
  • Puppeteer 最擅長偵錯：將「無頭」位元翻轉為 false，加上「slowMo」，您就會看到瀏覽器正在執行的工作。您甚至可以開啟 Chrome 開發人員工具來檢查測試環境。

為什麼 Puppeteer v.XXX 無法與 Chromium v.YYY 搭配使用？

Chromium 會將 Puppeteer 視為隱形實體。每個 Puppeteer 版本都會隨附特定版本的 Chromium，這是唯一保證可以搭配使用的版本。

這不是人工限制條件。Puppeteer 的許多工作是在 Chromium 存放區中展開。以下是常見的故事：

  1. 有檔名蟲子遭通報
  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 的觀點來看，「導覽」是指任何變更網頁網址的內容。 除了一般的導覽動作，瀏覽器還會點選網路來從網路伺服器擷取新文件，其中包括錨點導覽和 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 等授權格式。
    • 如果含有 executablePath 選項puppeteer.launch 的 executablePath 選項，您可以強制 Puppeteer 使用單獨安裝的版本 Chrome，而無法使用 Chromium。建議您只在需要支援這些媒體格式的 Chrome 正式版本時，才使用這項設定。
  • 由於 Puppeteer (所有設定) 會控制電腦版 Chromium 或 Chrome，因此不支援只有行動版 Chrome 支援的功能。這表示 Puppeteer 不支援 HTTP 即時串流 (HLS)。

我在測試環境中安裝 / 執行 Puppeteer。該如何尋求協助？

我們針對各種作業系統提供了疑難排解指南，其中列出必要的依附元件。

每次執行 npm ci 時，系統都會下載 Chromium。如何快取下載內容？

預設的下載路徑為 node_modules/puppeteer/.local-chromium。不過，您可以使用 PUPPETEER_DOWNLOAD_PATH 環境變數來變更該路徑。

Puppeteer 會使用該變數在啟動期間解析 Chromium 的執行檔位置，因此您也不必指定 PUPPETEER_EXECUTABLE_PATH。

例如，如要在 ~/.npm/chromium 中保留 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 方面的協助：

請務必先搜尋這些頻道，再張貼問題。