KechuAI

Vitest 4.0：Browser Mode 转正，测试框架向 E2E 迈了一大步

Vitest
测试
Vite
前端
Playwright
开源
2026/9/30
·

阅读时间: 大约 11 分钟

Vitest 4.0：Browser Mode 转正，测试框架向 E2E 迈了一大步

Vitest 4.0 官方发布封面

Vitest 4 于 2025 年 10 月 22 日正式发布，官方称之为”next Vitest major”。据 Koala 项目库点评，这一版最大的看点是浏览器模式（Browser Mode）正式稳定——开发者可以直接在真实浏览器里跑测试，并新增视觉回归测试、与 Playwright 深度集成。本文基于 Vitest 官方发布说明，梳理它到底改了什么、哪些是破坏性变更，以及它在 E2E 赛道上的真实位置。

一、背景：从单元测试到全栈测试框架

Vitest 最初靠”Vite 原生、 Jest 兼容、极快”切入单元/组件测试。但前端测试的痛点不止于跑得快：组件究竟在真实浏览器里、在真实布局和事件下表现如何？jsdom/happy-dom 这类 DOM 模拟能覆盖大部分逻辑，却覆盖不到真实渲染、样式、选区、iframe 与视口行为。Browser Mode 就是 Vitest 朝”真实浏览器测试”方向走的一步，4.0 这版把它从实验状态毕业。

二、Browser Mode 稳定：API 被重新设计

官方这版为 Browser Mode 做了一次不向后兼容的 API 整理，核心是把”浏览器提供者”拆成独立包：

  • 现在必须按所选引擎单独安装 @vitest/browser-playwright、@vitest/browser-webdriverio 或 @vitest/browser-preview；
  • 不再需要 /// <reference path="..."> 注释；
  • page 等上下文从 vitest/browser 导入（旧路径 @vitest/browser/context 在下个大版本前仍可用）；
  • @vitest/browser 本身可从依赖里移除——它被自动打进各 provider 包。

配置上通过 browser.provider 传入 provider 实例，并用 browser.instances 声明要在哪些浏览器（chromium 等）上跑。这一改动的官方理由是”更容易自定义选项”，代价是升级要动配置。

三、新能力：视觉回归与 Playwright Traces

3.1 视觉回归测试（Visual Regression）

4.0 在 Browser Mode 里新增 toMatchScreenshot 断言：

await expect(page.getByTestId('hero')).toMatchScreenshot('hero-section')

Vitest 会截取组件/页面截图，与参考图对比，检出意外的视觉改动。官方同时引入 toBeInViewport 匹配器，基于 IntersectionObserver 判断元素是否在视口内（支持 { ratio: 0.5 } 这种”50% 可见”的阈值）。

需要注意官方口径：视觉回归是新功能，“we will continue to iterate on this feature”——它尚在快速演进中。

3.2 Playwright Traces

Vitest 4 生成的 Playwright Trace Viewer：左侧是逐次键盘事件时间线，右侧是动作前后的 DOM 快照，底部是网络请求面板

开启后（test.browser.trace 或 --browser.trace），Vitest 可生成 Playwright Trace，支持 off / on / on-first-retry / on-all-retries / retain-on-failure 几档。Trace 在 HTML reporter 里以注解链接给出，用 Playwright Trace Viewer 打开——就是上面这张官方图：左侧是逐步动作（keydown/keyup）时间线，右侧是每个动作前后的 DOM 快照，底部还有网络请求。这对复现”偶发失败的浏览器测试”非常关键。

3.3 Locator 与调试增强

  • 新增 page.frameLocator（仅 playwright provider 支持）定位 iframe 内元素；
  • 每个 locator 暴露 length，可直接配 toHaveLength；
  • VSCode 扩展支持浏览器测试的”Debug Test”按钮；命令行 --inspect 可连 DevTools 手动调试。

四、类型与断言：Standard Schema 进测试

4.0 两个对 DX 很友好的改进：

  • 类型感知钩子：用 test.extend 扩展的 fixture，其 beforeEach/afterEach 能直接拿到扩展后的上下文（如 ({ todos }) => ...），不再像全局钩子那样对上下文”失明”；
  • expect.schemaMatching：一个接受 Standard Schema v1 对象的不对称匹配器，可在 toEqual / toMatchObject / toHaveBeenCalledWith 等所有等值匹配里用 Zod、Valibot、ArkType 的 schema 做形状断言——例如 expect(user).toEqual({ email: expect.schemaMatching(z.string().email()) })；
  • 另外把 Chai 的 assert 暴露到 expect.assert，方便在需要收窄类型时使用。

五、关键口径与破坏性变更

发布说明里明确列出需要读 Migration Guide 的破坏性变更，挑影响面大的几条：

  1. basic reporter 被移除，要用 ['default', { summary: false }] 替代；
  2. verbose reporter 行为改变：现在本地也会逐个打印完成的测试（以前只在 CI 如此），想保留旧行为需手动按 process.env.CI 条件切换；
  3. Browser Mode 的 import 路径与 provider 包拆分（见第二节）；
  4. 新增一批高级 API（experimental_parseSpecifications、动态 enableCoverage/disableCoverage、getSeed、waitForTestRunEnd 等），但带 experimental_ 前缀的仍属实验性。

要把”640+ contributors”这类数字读对：它是 Vitest Core 累计贡献者规模，不是 4.0 这一版的新增量。

六、适用 / 不适用场景

适合：

  • 已经在用 Vitest 做组件/单元测试，想在真实浏览器里覆盖交互、视口、iframe 的团队；
  • 需要视觉回归（截图对比）守护 UI 的项目；
  • 愿意用 Playwright provider 把浏览器测试和 trace 调试打通的前端团队。

不适合：

  • 只想跑纯单元测试、不需要真实浏览器的项目——Browser Mode 是可选的，不必为它升级整套；
  • 被 reporter 变更、import 路径变更影响、却没排迁移成本的团队——先读 Migration Guide。

七、客观分析：优势与局限

优势：

  1. 一套工具覆盖更广：从单元到真实浏览器、再到视觉回归与 trace，减少在 Vitest 与独立 E2E 框架间来回切换；
  2. 与 Playwright 生态打通：locator、trace、iframe 都复用 Playwright 心智；
  3. 类型与 schema 体验升级：类型感知钩子 + Standard Schema 匹配器，写断言更稳；
  4. 调试闭环完整：VSCode 一键 debug + Playwright Trace，排障不再靠猜。

局限（含官方口径）：

  1. 视觉回归仍在迭代：官方明说会继续改进，参考图管理、跨浏览器/跨环境截图一致性这类老问题不会因为一个版本就消失；
  2. 能力与 provider 绑定：frameLocator 仅 playwright provider 支持，换 WebDriverIO 就要降级预期；
  3. 破坏性变更不可避免：reporter、import 路径都要改，升级不是无痛；
  4. 不是完整 E2E 替代品：它补的是”在 Vitest 里跑真实浏览器”，复杂跨页面、多路由的端到端流程，专业 E2E 工具仍有其位置。

八、它意味着什么 / 谁该关注

Vitest 4 的信号很清楚：它不再满足于做”更快的 Jest”，而是要把浏览器真实环境、视觉回归、可观测调试都收进同一个测试入口。对已经押注 Vite/Vitest 的前端团队，这是顺理成章的升级路径；对还在 jsdom 里和”它在浏览器里居然不这样”搏斗的人，Browser Mode 转正值得一试。但请按官方建议先读 Migration Guide，并对视觉回归这一新能力保持”边用边等它成熟”的预期。

参考来源