瀏覽器

簡介

每個 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 可以透過在配置中設定專案，在多個瀏覽器和配置中執行您的測試。您也可以為每個專案新增不同的選項。

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 配置檔案的專案區段中定義。安裝 Playwright 時的預設配置為您提供 3 個專案：Chromium、Firefox 和 WebKit。預設選取第一個專案。

Projects section in VS Code extension

若要在多個專案（瀏覽器）上執行測試，請選取每個專案，方法是選取專案名稱旁邊的核取方塊。

Selecting projects to run tests on

Chromium

對於 Google Chrome、Microsoft Edge 和其他基於 Chromium 的瀏覽器，預設情況下，Playwright 使用開源 Chromium 建置版本。由於 Chromium 專案領先於品牌瀏覽器，因此當世界使用 Google Chrome N 時，Playwright 已經支援 Chromium N+1，該版本將在幾週後在 Google Chrome 和 Microsoft Edge 中發布。

Chromium：無頭殼層

Playwright 為有頭操作運送常規 Chromium 建置版本，並為無頭模式運送單獨的chromium 無頭殼層。

如果您僅在無頭殼層中執行測試（即未指定 channel 選項），例如在 CI 上，您可以透過在安裝期間傳遞 --only-shell 來避免下載完整的 Chromium 瀏覽器。

# only running tests headlessly
npx playwright install --with-deps --only-shell

Chromium：新的無頭模式

您可以透過使用 'chromium' 通道來選擇使用新的無頭模式。正如官方 Chrome 文件所述

另一方面，新的無頭模式是真正的 Chrome 瀏覽器，因此更真實、更可靠，並提供更多功能。這使其更適合高精準度的端對端 Web 應用程式測試或瀏覽器擴充功能測試。

有關詳細資訊，請參閱issue #33566。

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

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], channel: 'chromium' },
    },
  ],
});

使用新的無頭模式，您可以透過使用 --no-shell 選項來跳過在瀏覽器安裝期間下載無頭殼層

# only running tests headlessly
npx playwright install --with-deps --no-shell

Google Chrome & Microsoft Edge

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

可用的通道為 chrome、msedge、chrome-beta、msedge-beta、chrome-dev、msedge-dev、chrome-canary、msedge-canary。

警告

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

警告

Google Chrome 和 Microsoft Edge 已切換到新的無頭模式實作，該實作更接近常規有頭模式。這與 Playwright 在無頭執行時預設使用的chromium 無頭殼層不同，因此在某些情況下預期會有不同的行為。有關詳細資訊，請參閱issue #33566。

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

警告

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

使用 --help 選項執行以查看可以安裝的瀏覽器的完整清單。

何時使用 Google Chrome & Microsoft Edge，以及何時不使用？

預設值

大多數時候，使用具有最新 Chromium 的預設 Playwright 配置是一個好主意。由於 Playwright 領先於瀏覽器的穩定版通道，因此您可以安心地知道即將推出的 Google Chrome 或 Microsoft Edge 版本不會破壞您的網站。您可以及早發現破壞，並有大量時間在官方 Chrome 更新之前修復它。

迴歸測試

話雖如此，測試政策通常要求針對目前公開可用的瀏覽器執行迴歸測試。在這種情況下，您可以選擇其中一個穩定版通道 "chrome" 或 "msedge"。

媒體編解碼器

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

企業政策

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

Firefox

Playwright 的 Firefox 版本與最新的Firefox 穩定版建置版本相符。Playwright 無法與品牌版本的 Firefox 搭配使用，因為它依賴修補程式。

請注意，某些功能的可用性在很大程度上取決於底層平台，因此可能因作業系統而異。例如，Linux、macOS 和 Windows 之間可用的媒體編解碼器差異很大。

WebKit

Playwright 的 WebKit 源自最新的 WebKit 主要分支來源，通常在這些更新合併到 Apple Safari 和其他基於 WebKit 的瀏覽器之前。這提供了大量的提前時間來應對潛在的瀏覽器更新問題。Playwright 無法與品牌版本的 Safari 搭配使用，因為它依賴修補程式。相反，您可以使用最新的 WebKit 建置版本進行測試。

請注意，某些功能的可用性在很大程度上取決於底層平台，因此可能因作業系統而異。例如，Linux、macOS 和 Windows 之間可用的媒體編解碼器差異很大。雖然在 Linux CI 上執行 WebKit 通常是最經濟實惠的選項，但為了獲得最接近 Safari 的體驗，您應該在 mac 上執行 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

從成品儲存庫下載

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

有時，公司會維護內部成品儲存庫來託管瀏覽器二進制檔案。在這種情況下，可以將 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 瀏覽器下載到作業系統特定的快取資料夾中

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

安裝後，這些瀏覽器將佔用幾百 MB 的磁碟空間

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 更新到較新版本時回收它們。

注意

開發人員可以透過在其 .bashrc 中匯出 PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers 來選擇加入此模式。

密封安裝

您可以選擇加入密封安裝，並將二進制檔案放置在本機資料夾中

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

注意

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​

Chromium：無頭殼層​

Chromium：新的無頭模式​

Google Chrome & Microsoft Edge​

安裝 Google Chrome & Microsoft Edge​

何時使用 Google Chrome & Microsoft Edge，以及何時不使用？​

預設值​

迴歸測試​

媒體編解碼器​

企業政策​

Firefox​

WebKit​

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

從成品儲存庫下載​

管理瀏覽器二進制檔案​

密封安裝​

過時瀏覽器移除​

解除安裝瀏覽器​

簡介