浏览器

简介

每个版本的 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 等品牌浏览器上运行测试。它也可以在模拟的平板电脑和移动设备上运行。有关精选的桌面、平板电脑和移动设备的完整列表，请参阅设备参数注册表。

在不同浏览器上运行测试

通过在配置文件中设置项目 (projects)，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：无头 shell

Playwright 提供了用于有头操作的常规 Chromium 构建，以及用于无头模式的单独Chromium 无头 shell。

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

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

Chromium：新的无头模式

您可以使用 `'chromium'` 通道选择加入新的无头模式。正如 Chrome 官方文档所述

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

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

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

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

使用新的无头模式，您可以在浏览器安装期间使用 --no-shell 选项跳过下载无头 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 无头 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 在浏览器稳定版渠道之前就有了更新，这让人放心，即即将发布的 Google Chrome 或 Microsoft Edge 版本不会破坏您的网站。您可以尽早发现破坏，并在官方 Chrome 更新之前有充足的时间来修复它。

回归测试

尽管如此，测试策略通常要求针对当前公开可用的浏览器执行回归测试。在这种情况下，您可以选择一个稳定通道，"chrome" 或 "msedge"。

媒体编解码器

使用官方二进制文件的另一个原因是为了测试与媒体编解码器相关的功能。由于各种许可考虑和协议，Chromium 没有捆绑在 Google Chrome 或 Microsoft Edge 中的所有编解码器。如果您的网站依赖于此类编解码器（这种情况很少见），您也应该使用官方渠道。

企业策略

Google Chrome 和 Microsoft Edge 遵守企业策略，其中包括对功能、网络代理、阻碍测试的强制性扩展的限制。因此，如果您所属的组织使用此类策略，最简单的方法是在本地测试中使用捆绑的 Chromium，您仍然可以选择在通常不受此类限制的机器人上使用稳定渠道。

Firefox

Playwright 的 Firefox 版本与最近的Firefox Stable 构建匹配。Playwright 不适用于品牌版 Firefox，因为它依赖于补丁。

请注意，某些功能（严重依赖底层平台）的可用性可能因操作系统而异。例如，可用的媒体编解码器在 Linux、macOS 和 Windows 之间差异很大。

WebKit

Playwright 的 WebKit 源自最新的 WebKit main 分支源代码，通常在这些更新被纳入 Apple Safari 和其他基于 WebKit 的浏览器之前。这为应对潜在的浏览器更新问题提供了充足的提前期。Playwright 不适用于品牌版本的 Safari，因为它依赖于补丁。相反，您可以使用最新的 WebKit 构建版本进行测试。

请注意，某些严重依赖底层平台的功能的可用性可能因操作系统而异。例如，可用的媒体编解码器在 Linux、macOS 和 Windows 之间存在很大差异。虽然在 Linux CI 上运行 WebKit 通常是最经济的选择，但要获得最接近 Safari 的体验，您应该在 Mac 上运行 WebKit，例如如果您进行视频播放。

在防火墙或代理后安装

默认情况下，Playwright 从 Microsoft 的 CDN 下载浏览器。

有时公司维护一个内部代理，它会阻止直接访问公共资源。在这种情况下，Playwright 可以配置为通过代理服务器下载浏览器。

Bash
PowerShell
批处理

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
批处理

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
批处理

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
批处理

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_DOWNLOAD_HOST 的环境变量 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST。

Bash
PowerShell
批处理

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
批处理

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
批处理

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 install（独立安装）

您可以选择启用独立安装并将二进制文件放置在本地文件夹中

Bash
PowerShell
批处理

# 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 安装的浏览器列表。

npx playwright install --list

卸载浏览器

这将删除当前 Playwright 安装的浏览器（chromium、firefox、webkit）

npx playwright uninstall

要同时删除其他 Playwright 安装的浏览器，请传递 --all 标志

npx playwright uninstall --all

简介​

安装浏览器​

安装系统依赖项​

定期更新 Playwright​

配置浏览器​

在不同浏览器上运行测试​

Chromium​

Chromium：无头 shell​

Chromium：新的无头模式​

Google Chrome 和 Microsoft Edge​

安装 Google Chrome 和 Microsoft Edge​

何时使用 Google Chrome 和 Microsoft Edge，何时不使用？​

默认值​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

在防火墙或代理后安装​

从工件仓库下载​

管理浏览器二进制文件​

Hermetic install（独立安装）​

过期浏览器移除​

列出所有已安装的浏览器：​

卸载浏览器​

简介