浏览器

简介

每个版本的 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。第一个项目默认被选中。

image 2024 12 17 11 44 20 070

要在多个项目（浏览器）上运行测试，通过勾选每个项目名称旁边的复选框来选择项目。

image 2024 12 17 11 44 54 256

Chromium

对于 Google Chrome、Microsoft Edge 和其他基于 Chromium 的浏览器，默认情况下，Playwright 使用开源的 Chromium 构建。由于 Chromium 项目领先于品牌浏览器，当全球使用 Google Chrome N 时，Playwright 已经支持 Chromium N+1，这将在几周后发布到 Google Chrome 和 Microsoft Edge。

Playwright 提供了一个常规的 Chromium 构建版本用于有头操作，以及一个单独的 【Chromium 无头模式 shell】 用于无头模式。详情请参见问题 【#33566】。

在 CI 上优化下载大小

如果你仅在无头模式下运行测试（例如在 CI 上），你可以通过在安装时使用 --only-shell 避免下载常规版本的 Chromium。

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

选择新的无头模式

你可以通过使用 'chromium' 通道选择新的无头模式。正如【官方 Chrome 文档】所说：

“新的无头模式实际上是 Chrome 浏览器，因此更加真实、可靠，并提供更多功能。这使其更加适合进行高精度的端到端 Web 应用程序测试或浏览器扩展测试。”

详细信息请参见【问题 #33566】。

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

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

Google Chrome & Microsoft Edge

虽然 Playwright 可以下载并使用最新的 Chromium 构建，但它也可以在机器上操作品牌化的 Google Chrome 和 Microsoft Edge 浏览器（注意：Playwright 默认不安装它们）。特别是，当前版本的 Playwright 将支持这些浏览器的稳定和测试版本。

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

某些企业浏览器策略可能会影响 Playwright 启动和控制 Google Chrome 和 Microsoft Edge 的能力。在具有浏览器策略的环境中运行超出了 Playwright 项目的支持范围。

Google Chrome 和 Microsoft Edge 已经切换到新的无头模式实现，这比默认使用的 Chromium 无头版本更接近常规有头模式，因此在某些情况下可能会出现不同的行为。详细信息请参见问题 #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，何时不使用？

默认使用

大多数情况下，使用默认的 Playwright 配置和最新的 Chromium 是一个不错的选择。由于 Playwright 总是领先于浏览器的稳定版本，它可以确保即将发布的 Google Chrome 或 Microsoft Edge 不会破坏你的网站。你会在问题出现之前就捕捉到并有足够的时间进行修复。

回归测试

但是，测试政策通常要求使用当前公开可用的浏览器进行回归测试。在这种情况下，你可以选择稳定通道 "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 的体验，您应在 macOS 上运行 WebKit，尤其是进行视频播放时。

在防火墙或代理服务器后安装

默认情况下，Playwright 从微软的 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 从微软的 CDN 下载浏览器。

有时，企业会维护一个内部的工件仓库来托管浏览器二进制文件。在这种情况下，可以通过配置 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

也可以使用 per-browser（每个浏览器）的下载主机，通过配置 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

这些浏览器在安装时将占用几百兆字节的磁盘空间。

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