1. 模块定位

Browser 模式是 Vitest 区别于 Jest 的核心特性之一。它允许测试在真实浏览器环境中运行,而不是在 Node.js 中模拟 DOM(jsdom/happy-dom)。这对组件测试、Web API 测试(如 IndexedDB、Canvas、WebSocket)至关重要。

三个子包协作:

  • @vitest/browser — 浏览器模式核心(iframe 管理、WebSocket 通信)
  • @vitest/browser-playwright — Playwright 浏览器提供者
  • @vitest/browser-webdriverio — WebdriverIO 浏览器提供者

2. 架构设计

sequenceDiagram
    participant M as Main Process
    participant CDP as CDP/WebDriver
    participant B as Browser
    participant I as iframe

    M->>CDP: 启动浏览器
    CDP-->>B: browser ready
    M->>B: 创建 page
    B->>I: 创建 iframe (sandbox)
    M->>I: WebSocket 连接
    I-->>M: 注入 vitest runtime
    M->>I: import 测试文件
    I->>I: 执行测试
    I-->>M: 测试结果 (WebSocket)

图:浏览器模式架构 —— iframe 沙箱 + WebSocket 双向通信

3. 浏览器 Provider

两个 Provider 实现提供了不同的浏览器控制协议:

Provider协议浏览器
PlaywrightCDP (Chrome DevTools Protocol)Chromium / Firefox / WebKit
WebdriverIOWebDriver 协议Chrome / Safari / Edge / 移动端

Provider 负责:启动浏览器实例、创建 page、管理 iframe、注入脚本、转发日志和错误。

4. iframe 沙箱

每个测试文件在独立的 <iframe sandbox> 中运行,提供完全的 DOM/CSS/JS 隔离。iframe 内部加载 vitest 的浏览器端 runtime,通过 import() 加载测试文件。

iframe 的 sandbox 属性提供安全隔离——默认限制脚本执行、表单提交、弹窗等。Vitest 根据需要动态调整 sandbox 权限(如 allow-scripts、allow-same-origin)。

5. WebSocket 通信

iframe 与主进程通过 WebSocket 进行双向通信。通信协议使用 birpc——与 Worker 池相同的 RPC 机制:

  • 主进程 → iframe:发送测试文件列表、配置、startTests 指令
  • iframe → 主进程:返回测试结果、日志、错误信息

这种设计让浏览器模式与 Worker 模式共享相同的测试执行逻辑——唯一的区别是模块加载方式。

6. "如果我来写" 对比思考

🧠 问题:iframe 沙箱 vs 直接控制浏览器?

直觉方案:在 page 直接运行测试——不需要 iframe 隔离。

Vitest 的做法:每个测试文件在自己的 iframe 中运行,通过 sandbox 属性隔离。

差异分析:直接运行虽然简单,但多个测试文件之间会出现状态污染——DOM 修改、全局变量、事件监听器等。iframe 沙箱提供了接近原生进程级别的隔离,代价是每次需要重新加载 vitest runtime。这是一种经典的"空间换正确性"的权衡。