瀏覽器

簡介

每個版本的 Playwright 需要特定版本的瀏覽器二進位檔來操作。你將需要使用 Playwright CLI 來安裝這些瀏覽器。

隨著每次發佈，Playwright 都會更新其支援的瀏覽器版本，因此最新的 Playwright 將隨時支援最新的瀏覽器。這意味著每次更新 Playwright 時，您可能需要重新執行 install CLI 命令。

安裝瀏覽器

Playwright 可以安裝支援的瀏覽器。執行該命令而不帶參數將安裝預設的瀏覽器。

npx playwright install

您也可以通過提供參數來安裝特定的瀏覽器:

npx playwright install webkit

查看所有支援的瀏覽器:

npx playwright install --help

安裝系統相依套件

系統相依套件可以自動安裝。這對於 CI 環境很有用。

npx playwright install-deps

您也可以通過將其作為參數傳遞來安裝單個瀏覽器的相依套件:

npx playwright install-deps chromium

也可以將 install-deps 與 install 結合，這樣瀏覽器和作業系統的相依性就可以用一個指令安裝。

npx playwright install --with-deps chromium

請參閱系統需求以了解官方支援的作業系統。

定期更新 Playwright

保持 Playwright 版本為最新，您將能夠使用新功能並在最新的瀏覽器版本上測試您的應用程式，並在最新的瀏覽器版本公開發佈之前捕捉到錯誤。

# Update playwright
npm install -D @playwright/test@latest

# Install new browsers
npx playwright install

查看發行說明以了解最新版本和已發佈的變更。

# See what version of Playwright you have by running the following command
npx playwright --version

設定瀏覽器

Playwright 可以在 Chromium、WebKit 和 Firefox 瀏覽器以及 Google Chrome 和 Microsoft Edge 等品牌瀏覽器上執行測試。它還可以在模擬的平板電腦和行動裝置上執行。請參閱裝置參數註冊表以獲取選定桌面、平板電腦和行動裝置的完整清單。

在不同瀏覽器上執行測試

Playwright 可以透過在配置中設定 projects 來在多個瀏覽器和配置中執行你的測試。你也可以為每個 project 添加不同的選項。

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    /* Test against desktop browsers */
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    /* Test against mobile viewports. */
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or 'msedge-dev'
    },
  ],
});

Playwright 會預設執行所有專案。

npx playwright test

Running 7 tests using 5 workers

  ✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
  ✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Mobile Safari] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Google Chrome] › example.spec.ts:3:1 › basic test (2s)
  ✓ [Microsoft Edge] › example.spec.ts:3:1 › basic test (2s)

使用 --project 命令列選項來執行單個專案。

npx playwright test --project=firefox

Running 1 test using 1 worker

  ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)

使用 VS Code 擴充功能，你可以透過在 Playwright 側邊欄中勾選瀏覽器名稱旁的核取方塊來在不同瀏覽器上執行你的測試。這些名稱在你的 Playwright 配置文件中的 projects 部分定義。安裝 Playwright 時的預設配置會給你 3 個項目，Chromium、Firefox 和 WebKit。第一個項目是預設選中的。

Projects section in VS Code 擴充套件

要在多個專案（瀏覽器）上執行測試，請通過勾選專案名稱旁邊的複選框來選擇每個專案。

選擇專案來執行測試

Chromium

對於 Google Chrome、Microsoft Edge 和其他基於 Chromium 的瀏覽器，Playwright 預設使用開放原始碼的 Chromium 構建。由於 Chromium 項目領先於品牌瀏覽器，當世界使用 Google Chrome N 時，Playwright 已經支持 Chromium N+1，這將在幾週後在 Google Chrome 和 Microsoft Edge 中發佈。

Google Chrome & Microsoft Edge

雖然 Playwright 可以下載並使用最新的 Chromium 版本，但它也可以在機器上運行已安裝的 Google Chrome 和 Microsoft Edge 瀏覽器（請注意，Playwright 預設不會安裝它們）。特別是，目前的 Playwright 版本將支援這些瀏覽器的穩定版和 Beta 版頻道。

可用的頻道有 chrome、msedge、chrome-beta、msedge-beta 或 msedge-dev。

warning

某些企業瀏覽器政策可能會影響 Playwright 啟動和控制 Google Chrome 和 Microsoft Edge 的能力。在具有瀏覽器政策的環境中執行不在 Playwright 專案的範圍內。

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or "msedge-beta" or 'msedge-dev'
    },
  ],
});

安裝 Google Chrome & Microsoft Edge

如果 Google Chrome 或 Microsoft Edge 無法在您的機器上使用，您可以使用 Playwright 命令列工具來安裝它們:

npx playwright install msedge

warning

Google Chrome 或 Microsoft Edge 安裝將會安裝在作業系統的預設全域位置，覆蓋您當前的瀏覽器安裝。

使用 --help 選項來查看可安裝的瀏覽器完整列表。

什麼時候使用 Google Chrome 和 Microsoft Edge，什麼時候不使用？

預設

使用預設的 Playwright 設定和最新的 Chromium 大多數時候是個好主意。由於 Playwright 走在瀏覽器的穩定版本之前，這讓人放心，未來的 Google Chrome 或 Microsoft Edge 發佈不會破壞你的网站。你可以及早發現問題，並在官方 Chrome 更新之前有充足的時間修復。

回歸測試

話雖如此，測試策略通常要求對當前公開可用的瀏覽器進行回歸測試。在這種情況下，你可以選擇加入其中一個穩定的頻道，"chrome" 或 "msedge"。

媒體編解碼器

另一個使用官方二進位檔進行測試的原因是測試與媒體編解碼器相關的功能。由於各種許可考量和協議，Chromium 並沒有 Google Chrome 或 Microsoft Edge 捆綁的所有編解碼器。如果您的網站依賴這種編解碼器（這種情況很少見），您也會想要使用官方頻道。

企業政策

Google Chrome 和 Microsoft Edge 遵循企業政策，其中包括對功能的限制、網路代理、強制擴充功能，這些都會妨礙測試。因此，如果您是使用此類政策的組織的一部分，最簡單的方法是使用捆綁的 Chromium 進行本地測試，您仍然可以選擇在通常沒有此類限制的機器人上使用穩定通道。

Firefox

Playwright 的 Firefox 版本符合最近的 Firefox Stable build。Playwright 無法與品牌版本的 Firefox 一起使用，因為它依賴於補丁。

WebKit

Playwright 的 WebKit 源自最新的 WebKit 主分支來源，通常在這些更新被合併到 Apple Safari 和其他基於 WebKit 的瀏覽器之前。這為潛在的瀏覽器更新問題提供了大量的反應時間。由於依賴於補丁，Playwright 無法與品牌版本的 Safari 一起使用。相反，你可以使用最新的 WebKit 版本進行測試。請注意，某些功能的可用性可能會因為高度依賴底層平台而在不同的作業系統之間有所不同。

在防火牆或代理伺服器後安裝

預設情況下，Playwright 會從 Microsoft 的 CDN 下載瀏覽器。

有時公司會維護一個內部代理來阻止直接訪問公共資源。在這種情況下，可以配置 Playwright 通過代理伺服器下載瀏覽器。

Bash
PowerShell
Batch

HTTPS_PROXY=https://192.0.2.1 npx playwright install

$Env:HTTPS_PROXY="https://192.0.2.1"
npx playwright install

set HTTPS_PROXY=https://192.0.2.1
npx playwright install

如果代理的請求被攔截並使用自定義的不受信任證書授權機構（CA），並且在下載瀏覽器時產生 Error: self signed certificate in certificate chain，則必須在安裝瀏覽器之前通過 NODE_EXTRA_CA_CERTS 環境變數設置自定義根證書:

Bash
PowerShell
Batch

export NODE_EXTRA_CA_CERTS="/path/to/cert.pem"

$Env:NODE_EXTRA_CA_CERTS="C:\certs\root.crt"

set NODE_EXTRA_CA_CERTS="C:\certs\root.crt"

如果您的網路連接到 Playwright 瀏覽器檔案的速度很慢，您可以使用 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT 環境變數以毫秒為單位增加連接超時時間:

Bash
PowerShell
Batch

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
npx playwright install

set PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
npx playwright install

如果你正在安裝相依套件並且需要在 Linux 上使用代理，請確保以 root 使用者執行命令。否則，Playwright 將嘗試成為 root 並且不會將 HTTPS_PROXY 等環境變數傳遞給 linux 套件管理器。

sudo HTTPS_PROXY=https://192.0.2.1 npx playwright install-deps

從 artifact repository 下載

預設情況下，Playwright 會從 Microsoft 的 CDN 下載瀏覽器。

有時公司會維護一個內部 artifact 儲存庫來存放瀏覽器二進位檔。在這種情況下，可以配置 Playwright 使用 PLAYWRIGHT_DOWNLOAD_HOST 環境變數從自訂位置下載。

Bash
PowerShell
Batch

PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
npx playwright install

set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
npx playwright install

也可以使用每個瀏覽器的下載主機，使用 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 環境變數，這些變數優先於 PLAYWRIGHT_DOWNLOAD_HOST。

Bash
PowerShell
Batch

PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

$Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="http://203.0.113.3"
$Env:PLAYWRIGHT_DOWNLOAD_HOST="http://192.0.2.1"
npx playwright install

set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3
set PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1
npx playwright install

管理瀏覽器二進位檔

Playwright 下載 Chromium、WebKit 和 Firefox 瀏覽器到特定作業系統的快取資料夾:

%USERPROFILE%\AppData\Local\ms-playwright 在 Windows
~/Library/Caches/ms-playwright 在 macOS
~/.cache/ms-playwright 在 Linux

這些瀏覽器安裝後將佔用幾百兆位元組的磁碟空間:

du -hs ~/Library/Caches/ms-playwright/*
281M  chromium-XXXXXX
187M  firefox-XXXX
180M  webkit-XXXX

您可以使用環境變數覆蓋預設行為。安裝 Playwright 時，請要求它將瀏覽器下載到特定位置:

Bash
PowerShell
Batch

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
npx playwright install

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright install

當執行 Playwright 程式碼時，請它在共享位置搜尋瀏覽器。

Bash
PowerShell
Batch

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test

$Env:PLAYWRIGHT_BROWSERS_PATH="$Env:USERPROFILE\pw-browsers"
npx playwright test

set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright test

Playwright 會跟蹤需要那些瀏覽器的套件，並在你更新 Playwright 到較新版本時進行垃圾回收。

note

開發者可以通過在 .bashrc 中輸出 PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers 來選擇此模式。

Hermetic install

您可以選擇進行封閉安裝並將二進位檔放置在本地資料夾中:

Bash
PowerShell
Batch

# Places binaries to node_modules/playwright-core/.local-browsers
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

# Places binaries to node_modules\playwright-core\.local-browsers
$Env:PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install

# Places binaries to node_modules\playwright-core\.local-browsers
set PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install

note

PLAYWRIGHT_BROWSERS_PATH 不會更改 Google Chrome 和 Microsoft Edge 的安裝路徑。

過時瀏覽器移除

Playwright 會追蹤使用其瀏覽器的客戶端。當不再有客戶端需要特定版本的瀏覽器時，該版本會從系統中刪除。這樣你可以安全地使用不同版本的 Playwright 實例，同時不會浪費磁碟空間來存放不再使用的瀏覽器。

要選擇退出未使用瀏覽器的移除，你可以設定 PLAYWRIGHT_SKIP_BROWSER_GC=1 環境變數。

移除瀏覽器

這將移除當前 Playwright 安裝的瀏覽器 (chromium, firefox, webkit):

npx playwright uninstall

要移除其他 Playwright 安裝的瀏覽器，請傳遞 --all 旗標:

npx playwright uninstall --all

簡介​

安裝瀏覽器​

安裝系統相依套件​

定期更新 Playwright​

設定瀏覽器​

在不同瀏覽器上執行測試​

Chromium​

Google Chrome & Microsoft Edge​

安裝 Google Chrome & Microsoft Edge​

什麼時候使用 Google Chrome 和 Microsoft Edge，什麼時候不使用？​

預設​

回歸測試​

媒體編解碼器​

企業政策​

Firefox​

WebKit​

在防火牆或代理伺服器後安裝​

從 artifact repository 下載​

管理瀏覽器二進位檔​

Hermetic install​

過時瀏覽器移除​

移除瀏覽器​

簡介