浏览器

介绍

每个版本的 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 配置文件中的 projects 部分定义。安装 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 已支持将在几周后在 Google Chrome 和 Microsoft Edge 中发布的 Chromium N+1 版本。

Chromium: headless shell

Playwright 随附一个用于有头操作的常规 Chromium 构建版本，以及一个单独的 chromium headless shell 用于无头模式。

如果你只在 headless shell 中运行测试（即未指定 channel 选项），例如在 CI 上，你可以通过在安装时传递 --only-shell 来避免下载完整的 Chromium 浏览器。

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

Chromium: 新的无头模式

你可以使用 'chromium' channel 选择新的无头模式。正如官方 Chrome 文档所述

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

有关详细信息，请参阅问题 #33566。

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

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

使用新的无头模式，你可以在浏览器安装期间使用 --no-shell 选项跳过下载 headless shell

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

Google Chrome 与 Microsoft Edge

虽然 Playwright 可以下载和使用最新的 Chromium 构建版本，但它也可以针对机器上可用的品牌 Google Chrome 和 Microsoft Edge 浏览器进行操作（注意 Playwright 默认不会安装它们）。特别是，当前 Playwright 版本将支持这些浏览器的 Stable 和 Beta channel。

可用的 channel 包括 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 headless shell 不同，因此在某些情况下预计会有不同的行为。有关详细信息，请参阅问题 #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 先于浏览器的 Stable channel，因此即将发布的 Google Chrome 或 Microsoft Edge 版本不会破坏你的网站。你可以及早发现问题，并在官方 Chrome 更新发布前有很多时间来修复它。

回归测试

话虽如此，测试策略通常要求对当前公开可用的浏览器执行回归测试。在这种情况下，你可以选择使用其中一个 stable channel："chrome" 或 "msedge"。

媒体编解码器

使用官方二进制文件进行测试的另一个原因是测试与媒体编解码器相关的功能。由于各种许可和协议限制，Chromium 不包含 Google Chrome 或 Microsoft Edge 捆绑的所有编解码器。如果你的网站依赖于此类编解码器（这种情况很少见），你也会希望使用官方 channel。

企业策略

Google Chrome 和 Microsoft Edge 遵守企业策略，其中包括对功能、网络代理和强制扩展程序的限制，这些都会妨碍测试。因此，如果你所在的组织使用此类策略，最简单的方法是使用捆绑的 Chromium 进行本地测试，你仍然可以在通常没有此类限制的机器人上选择使用 stable channel。

Firefox

Playwright 的 Firefox 版本与最新的 Firefox Stable 构建版本匹配。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

从 artifact 仓库下载

默认情况下，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 浏览器下载到特定于操作系统的缓存文件夹中

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 来选择此模式。

Hermetic 安装

你可以选择 hermetic 安装并将二进制文件放在本地文件夹中

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: headless shell​

Chromium: 新的无头模式​

Google Chrome 与 Microsoft Edge​

安装 Google Chrome 与 Microsoft Edge​

何时使用 Google Chrome 与 Microsoft Edge 以及何时不使用？​

默认设置​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理后安装​

从 artifact 仓库下载​

管理浏览器二进制文件​

Hermetic 安装​

过期浏览器移除​

卸载浏览器​

介绍