简体中文

English
简体中文

浏览器模式

Rstest 提供了浏览器模式（Browser Mode），允许你在真实浏览器中运行测试，而不是使用 jsdom 或 happy-dom 等模拟环境。

什么是浏览器模式？

浏览器模式使用 Playwright 在真实浏览器（Chromium、Firefox 或 WebKit）中执行你的测试代码。这意味着你的测试将在与生产环境完全一致的浏览器 API 和行为下运行。

Note

与 Node 模式一致，当有未处理的错误或 Promise rejection 从测试文件中逸出时，即使该文件中的所有测试都通过，浏览器模式也会将该文件判定为失败。如果某个 rejection 是预期的，请在测试内 await 该 Promise 或为其挂上处理函数，避免它逸出到页面。

Locator API

Browser Mode 现在支持 Playwright 风格的 Locator 工作流：你可以使用 page.getBy* 进行元素定位，再通过 expect.element(locator) 完成自动等待断言。

这种写法适合希望使用语义化定位（role/label/text）和链式断言的场景，让组件测试和 DOM 测试更接近真实用户交互语义。

详细用法见浏览器交互。

何时使用浏览器模式

使用以下决策树来判断是否需要浏览器模式：

依赖真实浏览器 API? ─── 是 ─▶ ✅ 浏览器模式
         │ 否
         ▼
需要跨浏览器测试?  ─── 是 ─▶ ✅ 浏览器模式
         │ 否
         ▼
jsdom 中行为异常?  ─── 是 ─▶ ✅ 浏览器模式
         │ 否
         ▼
    💡 可用 jsdom

推荐

即使你的测试在 jsdom 中能正常运行，我们仍然推荐使用浏览器模式。具体优势见下方对比表。

浏览器模式 vs jsdom/happy-dom

浏览器模式与 jsdom/happy-dom 是两种不同的权衡：浏览器模式提供完整的浏览器兼容性和可视化调试，但会消耗更多资源；jsdom/happy-dom 运行更快、更轻量，但只能模拟部分浏览器 API。

特性	浏览器模式	jsdom / happy-dom
浏览器 API 完整性	✅ 完整支持	⚠️ 部分模拟
Canvas / WebGL	✅ 原生支持	❌ 不支持或需 polyfill
CSS 计算样式	✅ 真实渲染	⚠️ 有限支持
Web Workers	✅ 原生支持	❌ 不支持
执行速度	⚠️ 较慢	✅ 更快
资源消耗	⚠️ 较高	✅ 较低
调试体验	✅ 可视化调试	⚠️ 仅控制台
跨浏览器测试	✅ 支持多浏览器	❌ 不支持

配置兼容性

大部分配置项在浏览器模式下的行为与 Node 模式一致。下表集中列出了例外情况——被忽略的 node-only 配置（设置为非默认值时会触发一次性警告）、暂不支持的能力，以及调度语义不同的选项：

配置项 / API	浏览器模式下的行为
coverage.provider: 'v8'	不支持。纯浏览器运行会直接报错（`rstest list` 除外）；node + 浏览器混合运行会告警，浏览器项目文件没有覆盖率，node 项目仍使用 v8。浏览器覆盖率请使用默认的 `istanbul` provider。
rs.mock 系列	暂不支持——`rs.mock`、`rs.doMock`、`rs.importActual`、`rs.mockRequire` 在浏览器测试中会抛出错误。
includeSource	暂不支持。源码内测试块只在 node 模式项目中运行。
isolate	被忽略——每个测试文件始终运行在全新的浏览器 context/page 中。纯浏览器运行设置 `isolate: false` 时会告警。
pool.type / pool.execArgv	被忽略——它们是 node 进程机制。
pool.maxWorkers	headless 运行时，测试文件在最多 `maxWorkers` 个浏览器 context 中并行执行；headed 运行时测试文件始终串行执行，因为所有测试共享同一个可见的容器页面。
testEnvironment	被忽略——真实浏览器本身就是运行环境。
detectAsyncLeaks、logHeapUsage	被忽略——node-only 机制。
bail	headless 运行下支持：达到失败上限后，Rstest 停止调度剩余文件。已在并行执行中的文件会先跑完，所以仍可能出现少量新结果。headed 调试 UI（`headless: false`）不应用 bail。

下一步

快速开始 - 配置并运行你的第一个浏览器测试
浏览器交互 - 使用 page + expect.element 编写语义化测试
框架集成 - 各框架的完整配置和组件测试示例
用户交互 - 模拟用户点击、输入等操作