浏览器

简介

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

有关详细信息，请参阅issue #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 版本将支持这些浏览器的 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 无头 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，何时不使用？

默认值

大多数情况下，使用默认的 Playwright 配置和最新的 Chromium 是一个好主意。由于 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 主分支源代码，通常在这些更新合并到 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 浏览器下载到特定于操作系统的缓存文件夹中

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

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

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：无头 shell​

Chromium：新的无头模式​

Google Chrome & Microsoft Edge​

安装 Google Chrome & Microsoft Edge​

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

默认值​

回归测试​

媒体编解码器​

企业策略​

Firefox​

WebKit​

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

从工件仓库下载​

管理浏览器二进制文件​

密封安装​

过时浏览器删除​

卸载浏览器​

简介