vitest

Vitest

当工作涉及 Vitest 时使用此技能：编写/运行测试、配置、模拟/快照、覆盖率、浏览器模式、项目/池、报告器，或从 Jest / Vitest 3 / Vitest 4 迁移。

快照：[email protected]（2026-10-01）。如果版本不同，请根据 source-map.md 刷新内容。

工作流

1. 检查本地 Vitest 环境：
   • 包版本：vitest 和版本对齐的 @vitest/*（快照版本为 5.0.3）。Node ^22.12 || ^24 || >=26。Vite 对等依赖 ^6.4 || ^7 || ^8（必需；使用 Yarn 时必须显式列出 vite）。
   • 配置：专用的 vitest.config.*（会完全覆盖 vite.config）与 Vite 配置中的 test: {}。不会从父目录查找配置。
   • 脚本：CI 中优先使用 vitest run；如果项目使用 Vitest，请勿使用 bun test（Bun 的运行器），改用 bun run test / bunx vitest。
   • 环境：node（默认）与 jsdom / happy-dom，以及 Browser Mode 项目。
   • 产物：项目根目录下的 .vitest/（将其加入 gitignore）。
2. 日常使用方法请先参阅 usage-guide.md。
3. 版本不一致，或任务涉及浏览器/覆盖率/迁移时，请刷新文档。从 source-map.md 开始。
4. 按需查阅更深入的资料：
   • 配置、CLI、测试 API、环境、设置：config-cli-api.md。
   • vi 模拟、vi.when、计时器、环境变量替身、快照：mocking-snapshots.md。
   • 覆盖率、浏览器模式、项目、池、报告器、基准测试：coverage-browser-projects.md。
   • Jest / Vitest 3 → 4 / 4 → 5：migration.md。
5. 优先使用 Vitest 5.x API（默认 extends: true 的 projects、maxWorkers、浏览器提供程序工厂、作为测试上下文 fixture 的 bench、vi.when）。确保 @vitest/* 包与 vitest 版本一致。
6. 使用最精简且有效的命令进行验证（vitest run path -t "name"、覆盖率，或浏览器项目）。仅在调整池/隔离/缓存时使用 vitest doctor。

核心判断

• Vitest 是由 Vite 驱动、兼容 Jest API 的测试运行器，不是 Bun 内置的 bun test。
• CI / 钩子：始终使用 vitest run（或 --run）。普通的 vitest 会进入监听模式；在非交互环境中会持续运行，除非 CI/非 TTY 环境强制其运行一次。
• 除非设置了 globals: true，否则应从 vitest 导入。优先显式导入，以便 Agent 更清楚地理解代码。
• vi.mock / vi.unmock / vi.hoisted 会被提升，且必须位于顶层；嵌套调用会抛出错误。工厂函数不能闭包捕获未提升的局部变量。
• clearMocks 默认值为 true（每个测试前清除调用历史，但保留实现）。共享模拟的并发测试可能需要设置 clearMocks: false。
• 并发测试与快照/断言：使用测试回调中的上下文 expect，不要使用全局 expect。
• 始终对 resolves / rejects / toMatchFileSnapshot / expect.poll 使用 await；未等待的异步断言会导致测试失败。
• 默认池为 forks。原生扩展表现异常时，优先使用它，而非 threads。
• 专用的 vitest.config.* 会忽略 vite.config 选项；扩展 Vite 插件/别名时请使用 mergeConfig。
• 内联的 test.projects 会继承根配置（默认 extends: true），并可能共享 Vite 服务器。文件/目录项目不会继承。
• 项目中的覆盖率仅作用于根配置；请显式设置 coverage.include。模式会匹配相对于项目根目录的路径（不支持 contains）。
• Browser Mode 不等同于 environment: 'jsdom'；请使用 browser.enabled 和提供程序包。定位器默认采用精确匹配。
• bench 不是顶层导入项；请在 *.bench.* 文件中使用 { bench } fixture。
• Vite 会转换测试，但不会进行类型检查；请使用可选的 typecheck 或项目的 tsc 单独检查。

验证

优先使用仓库自带的命令。对于有意义的 Vitest 工作，覆盖相关子集：

• 运行 bunx vitest --version，并确认 @vitest/* 版本一致。
• 运行聚焦的 vitest run <file> -t "<name>"（或使用 :line 过滤器）。完整名称使用 >（-t 'suite > test'）。
• 仅在有意更新时使用 -u / watch u 更新快照；检查差异。
• 覆盖率：在阈值或报告有意义时运行 vitest run --coverage。
• Browser 项目：在 UI/组件测试发生变更时，运行无头 chromium 冒烟测试。
• 迁移：确保不再存在 workspace、字符串形式的 browser providers、poolOptions、test(name, fn, options)、嵌套的 vi.mock、顶层 bench 导入、test.sequential 或 browser.api。

报告运行了哪些检查、哪些未运行，以及仍存在哪些 Vitest 版本假设。