自动化测试 / 系统课时

安装浏览器运行环境

安装浏览器运行环境

Playwright 的 npm 包安装成功,并不代表浏览器已经可以启动。本课解决浏览器可执行文件缺失、下载失败或系统依赖不完整的问题,完成浏览器安装,并通过实际启动 Chromium 验证运行环境是否可用。

学习目标

  • 理解 Playwright 包、浏览器二进制文件和系统依赖之间的关系。
  • 安装 Playwright 支持的浏览器,并根据需要选择单个浏览器。
  • 验证浏览器能否启动,定位常见的安装与环境问题。

浏览器组件说明

Playwright 默认使用与当前 Playwright 版本匹配的浏览器构建,而不是直接调用系统已经安装的 Chrome 或 Firefox。安装 npm 依赖和下载浏览器是两个不同的步骤。

Playwright 主要支持三种浏览器引擎:

  • Chromium:用于测试 Chromium 内核浏览器的行为。
  • Firefox:用于检查 Firefox 浏览器的兼容性。
  • WebKit:用于检查 WebKit 引擎相关的页面行为。

浏览器文件通常下载到用户级缓存目录,与项目中的 node_modules 分开存放。Playwright 负责查找匹配版本的浏览器,并在执行测试时启动浏览器进程。测试结束后应关闭浏览器,释放相关资源。

Playwright 浏览器组件与启动生命周期

需要注意,浏览器二进制文件与操作系统依赖也不是一回事。即使 Chromium 已经下载成功,在缺少必要共享库的 Linux 环境中,浏览器仍然可能启动失败。

安装浏览器

先确认已经在项目中安装 @playwright/test,并进入包含 package.json 的项目根目录。运行以下命令安装当前 Playwright 版本所需的默认浏览器:

bash
npx playwright install

预期结果:命令正常结束,退出码为 0。首次安装时,终端通常显示浏览器下载进度及缓存位置,例如以下日志片段:

text
Downloading Chromium <ID> ...
Chromium <ID> downloaded to <PATH>

实际版本、下载地址、缓存路径和日志内容可能不同。命令还会处理 Firefox、WebKit 及所需的辅助组件;如果对应文件已经缓存,可能不会再次下载,也不一定显示上述日志。

如果项目只需要 Chromium,例如目前只编写 Chromium 浏览器测试,可以只安装该浏览器:

bash
npx playwright install chromium

预期结果:命令成功退出,当前 Playwright 版本对应的 Chromium 浏览器文件可用。如果文件已经存在,安装程序通常直接复用缓存。该命令不会同时安装 Firefox 和 WebKit。

验证浏览器可启动

下载完成不等于运行成功。最直接的验证方法是调用 Playwright 的 chromium.launch(),尝试启动浏览器并正常关闭。

在项目根目录创建 verify-browser.cjs 文件,写入以下代码:

js
const { chromium } = require('@playwright/test');

async function verify() {
  // 使用无头模式,避免依赖可见的桌面窗口
  const browser = await chromium.launch({ headless: true });
  console.log('Chromium launch OK');

  // 验证完成后释放浏览器进程
  await browser.close();
}

verify().catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

在同一项目目录执行 node verify-browser.cjs。

预期输出:

text
Chromium launch OK

出现这行输出且进程正常退出,表示 Playwright 已经找到 Chromium 浏览器文件,并且浏览器能够在当前操作系统环境中启动和关闭。

如果出现 Executable doesn't exist,通常表示所需浏览器尚未下载、版本不匹配,或者安装与运行时使用了不同的浏览器缓存目录。如果出现缺少共享库的错误,则需要检查操作系统依赖,而不是反复执行同一段 JavaScript。

常见失败处理

浏览器下载失败

如果安装时出现网络连接超时、下载中断或证书相关错误,先确认当前环境可以访问浏览器下载源。需要通过代理访问外网时,应正确配置 HTTPS_PROXY 等环境变量,再重新执行安装命令。

下载中断后可以直接重试。Playwright 会检查已有浏览器文件,无需手动删除整个项目的 node_modules。

Linux 系统依赖缺失

在受支持的 Ubuntu、Debian 等 Linux 环境中,如果浏览器已下载但启动时报缺少系统库,可以执行:

bash
npx playwright install --with-deps chromium

预期结果:命令安装 Chromium 所需的操作系统依赖和浏览器文件并正常退出。安装系统软件包可能需要管理员权限,具体日志取决于 Linux 发行版和已安装的软件包。

该命令不是所有操作系统都需要执行的步骤。在 Windows 和 macOS 上,应优先根据实际启动错误排查,不要照搬 Linux 的系统依赖安装方式。

浏览器版本或缓存路径不一致

如果安装成功后仍提示找不到可执行文件,先检查安装命令与运行脚本是否使用同一项目的 Playwright 依赖版本。

如果配置了 PLAYWRIGHT_BROWSERS_PATH,还需要确认安装和运行阶段使用相同的环境变量值。否则浏览器可能下载到了一个目录,而运行时却在另一个目录查找。

修复后重新运行 node verify-browser.cjs。只有实际输出 Chromium launch OK,并且进程正常退出,才说明本课的 Chromium 浏览器运行环境通过了验证。Firefox 和 WebKit 仍需要分别进行启动验证,不能由 Chromium 的成功结果直接推断它们也可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安装浏览器运行环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通