close
Rstest
  • 简体中文

      • 浏览器模式

      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。
      isolate被忽略——每个测试文件始终运行在全新的浏览器 context/page 中。纯浏览器运行设置 isolate: false 时会告警。
      pool.type / pool.execArgv被忽略——它们是 node 进程机制。
      pool.maxWorkersheadless 运行时，测试文件在最多 maxWorkers 个浏览器 context 中并行执行；headed 运行时测试文件始终串行执行，因为所有测试共享同一个可见的容器页面。
      testEnvironment被忽略——真实浏览器本身就是运行环境。
      detectAsyncLeaks、logHeapUsage被忽略——node-only 机制。
      bailheadless 运行下支持：达到失败上限后，Rstest 停止调度剩余文件。已在并行执行中的文件会先跑完，所以仍可能出现少量新结果。headed 调试 UI（headless: false）不应用 bail。

      模块 mock（rs.mock 系列）与 includeSource 源码内测试的行为与 Node 模式一致。rs.mockRequire 在浏览器测试中同样可用，但它面向 CommonJS 互操作场景——编写浏览器测试时优先使用 rs.mock / rs.doMock。

      下一步