浏览器

简介

每个 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：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 应用程序测试或浏览器扩展测试。

有关详细信息，请参阅 issue #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 渠道。

可用的渠道有 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 不同，因此在某些情况下，预计行为会有所不同。有关详细信息，请参阅 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 领先于浏览器的 Stable 渠道，因此你可以放心，即将发布的 Google Chrome 或 Microsoft Edge 版本不会破坏你的网站。你可以尽早发现中断，并有足够的时间在官方 Chrome 更新之前修复它。

回归测试

话虽如此，测试策略通常要求针对当前公开可用的浏览器执行回归测试。在这种情况下，你可以选择 Stable 渠道之一，"chrome" 或 "msedge"。

媒体编解码器

使用官方二进制文件进行测试的另一个原因是测试与媒体编解码器相关的功能。由于各种许可考虑和协议，Chromium 不具有 Google Chrome 或 Microsoft Edge 捆绑的所有编解码器。如果你的网站依赖于这种编解码器（这种情况很少见），那么你还需要使用官方渠道。

企业策略

Google Chrome 和 Microsoft Edge 遵守企业策略，其中包括对功能、网络代理、强制扩展的限制，这些限制会妨碍测试。因此，如果你是使用此类策略的组织的一部分，那么最容易使用捆绑的 Chromium 进行本地测试，你仍然可以选择通常不受此类限制的机器人上的 Stable 渠道。

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

从工件库下载

默认情况下，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

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

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​

在防火墙或代理后面安装​

从工件库下载​

管理浏览器二进制文件​

Hermetic 安装​

过时浏览器删除​

卸载浏览器​

简介