跳转到主要内容

浏览器

简介​

每个 Playwright 版本都需要特定版本的浏览器二进制文件才能运行。您需要使用 Playwright CLI 来安装这些浏览器。

每次发布时，Playwright 都会更新其支持的浏览器版本，以便最新的 Playwright 始终支持最新的浏览器。这意味着每次您更新 Playwright 时，您可能需要重新运行 install CLI 命令。

安装浏览器​

Playwright 可以安装受支持的浏览器。运行不带参数的命令将安装默认浏览器。

playwright install

您还可以通过提供参数来安装特定的浏览器

playwright install webkit

查看所有受支持的浏览器

playwright install --help

安装系统依赖项​

系统依赖项可以自动安装。这对于 CI 环境非常有用。

playwright install-deps

您还可以通过将浏览器作为参数传递来安装单个浏览器的依赖项

playwright install-deps chromium

也可以将 install-deps 与 install 结合使用，以便使用单个命令安装浏览器和操作系统依赖项。

playwright install --with-deps chromium

有关官方支持的操作系统，请参阅系统要求。

配置浏览器​

Playwright 可以在 Chromium、WebKit 和 Firefox 浏览器以及 Google Chrome 和 Microsoft Edge 等品牌浏览器上运行测试。它还可以在模拟的平板电脑和移动设备上运行。有关选定的桌面、平板电脑和移动设备的完整列表，请参阅设备参数注册表。

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

在特定的浏览器上运行测试

pytest test_login.py --browser webkit

在多个浏览器上运行测试

pytest test_login.py --browser webkit --browser firefox

针对移动视口进行测试

pytest test_login.py --device="iPhone 13"

针对品牌浏览器进行测试

pytest test_login.py --browser-channel msedge

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 构建版本，并为 headless 模式提供单独的chromium headless shell。

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

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

Chromium：新的 headless 模式​

您可以通过使用 'chromium' channel 选择新的 headless 模式。正如官方 Chrome 文档所说

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

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

pytest test_login.py --browser-channel chromium

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

# only running tests headlessly
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 已切换到新的 headless 模式实现，该实现更接近于常规有头模式。这与 Playwright 在 headless 运行时默认使用的chromium headless shell不同，因此在某些情况下可能会出现不同的行为。有关详细信息，请参阅issue #33566。

pytest test_login.py --browser-channel msedge

或者，当直接使用库时，您可以在启动浏览器时指定浏览器频道

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Channel can be "chrome", "msedge", "chrome-beta", "msedge-beta" or "msedge-dev".
    browser = p.chromium.launch(channel="msedge")
    page = browser.new_page()
    page.goto("https://playwright.net.cn")
    print(page.title())
    browser.close()

安装 Google Chrome & Microsoft Edge​

如果您的机器上没有 Google Chrome 或 Microsoft Edge，您可以使用 Playwright 命令行工具安装它们

playwright install msedge
警告

Google Chrome 或 Microsoft Edge 安装将安装在您操作系统的默认全局位置，从而覆盖您当前的浏览器安装。

使用 --help 选项运行以查看可以安装的浏览器的完整列表。

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

默认值​

大多数情况下，使用带有最新 Chromium 的默认 Playwright 配置是一个好主意。由于 Playwright 领先于浏览器的 Stable 频道，因此您可以放心，即将到来的 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 配置为通过代理服务器下载浏览器。

pip install playwright
HTTPS_PROXY=https://192.0.2.1 playwright install

如果代理的请求被自定义不受信任的证书颁发机构 (CA) 拦截，并且在下载浏览器时导致 Error: self signed certificate in certificate chain，您必须通过NODE_EXTRA_CA_CERTS环境变量设置您的自定义根证书，然后再安装浏览器

export NODE_EXTRA_CA_CERTS="/path/to/cert.pem"

如果您的网络连接到 Playwright 浏览器存档的速度很慢，您可以使用 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT 环境变量增加连接超时时间（以毫秒为单位）

pip install playwright
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 playwright install

如果您正在安装依赖项并且需要在 Linux 上使用代理，请确保以 root 用户身份运行该命令。否则，Playwright 将尝试成为 root 用户，并且不会将 HTTPS_PROXY 等环境变量传递给 Linux 包管理器。

sudo HTTPS_PROXY=https://192.0.2.1 playwright install-deps

从工件存储库下载​

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

有时公司维护内部工件存储库来托管浏览器二进制文件。在这种情况下，可以将 Playwright 配置为使用 PLAYWRIGHT_DOWNLOAD_HOST 环境变量从自定义位置下载。

pip install playwright
PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 playwright install

也可以使用每个浏览器的下载主机，使用 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST、PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST 和 PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST 环境变量，这些变量优先于 PLAYWRIGHT_DOWNLOAD_HOST。

pip install playwright
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 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 时，要求它将浏览器下载到特定位置

pip install playwright
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install

运行 Playwright 脚本时，要求它在共享位置搜索浏览器。

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.py

Playwright 会跟踪需要这些浏览器的软件包，并在您将 Playwright 更新到较新版本时对其进行垃圾回收。

注意

开发人员可以通过在其 .bashrc 中导出 PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers 来选择此模式。

过时浏览器删除​

Playwright 会跟踪使用其浏览器的客户端。当不再有客户端需要特定版本的浏览器时，该版本将从系统中删除。这样，您可以安全地使用不同版本的 Playwright 实例，同时又不会浪费不再使用的浏览器的磁盘空间。

要选择退出未使用浏览器删除，您可以设置 PLAYWRIGHT_SKIP_BROWSER_GC=1 环境变量。

卸载浏览器​

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

playwright uninstall

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

playwright uninstall --all