vitest

Vite 原生的单元测试框架，由 Vite 团队维护。复用 vite 的转换管道与配置，TS/JSX/ESM 开箱即用无需 babel；API 兼容 Jest（describe/it/expect/mock 可直接迁移），是 Vite 项目的事实标准测试方案。当前主线为 4.x（4.0：Browser Mode 转正 + 视觉回归测试 + 全新 UI；4.1：支持 Vite 8、复用项目已安装的 vite、Test Tags 按标签分组过滤）。

核心命令

vitest              # 开发环境默认进入 watch 模式（有 tty 时）
vitest run          # 单次执行后退出，CI 标准用法
vitest watch        # 强制 watch 模式（等同开发环境默认行为）
vitest dev          # watch 模式的别名
vitest bench        # 运行基准测试（Tinybench 驱动，*.bench.ts）
vitest init         # 初始化配置（生成 vitest.config.ts、装依赖）
vitest list         # 不执行，只列出匹配到的测试（--filesOnly 仅列文件）
vitest related      # 只跑与指定源文件相关的测试（配合 git diff 做精准回归）
vitest start        # 启动调试服务（--inspect-brk 挂接 Node inspector）

位置参数是文件名过滤器（支持多模式、glob），例如 vitest run src/utils 只跑路径匹配的文件。

常用选项

-t, --testNamePattern <pattern>   # 按测试名过滤（正则），4.0 新增
--coverage                        # 覆盖率（v8 默认 / istanbul 可选）
--ui                              # 打开 Web UI（4.0 全新界面：树状视图/慢测试热图/快照预览）
--browser                         # Browser Mode，真实浏览器中跑组件测试（4.0 转正）
--environment <env>               # node（默认）/ jsdom / happy-dom
--reporter <name>                 # verbose/dot/json/junit/html 等
--pool <pool>                     # 并发池：forks（默认）/ threads / vmForks / vmThreads
--shard <i/n>                     # 分片执行，如 --shard 1/3，CI 多机分摊
--bail <n>                        # 失败 n 个即停，默认 0 不中断
--changed [ref]                   # 只跑受 git 变更影响的测试（可给分支/commit）
--sequence.shuffle                # 打乱执行顺序，暴露用例间依赖
--update                          # 更新快照（慎用，CI 里禁用）

watch 模式交互键

watch 运行时终端支持快捷键：a 重跑全部、f 只跑失败过的、t 按测试名过滤、p 按文件名过滤、u 更新快照、q 退出。CI 环境无 tty 时自动退化为单次执行。

配置文件

vitest.config.ts 优先于 vite.config.ts（两者都存在时用前者）：

import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,           // describe/it/expect 免 import
    coverage: { provider: 'v8', reporter: ['text', 'html'] },
    include: ['src/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    projects: ['packages/*'], // monorepo 多项目（原 workspace）
  },
})

实用组合

# 只跑本次 git 改动相关的测试
vitest related $(git diff --name-only HEAD)
 
# CI 单次执行 + 覆盖率 + junit 产物
vitest run --coverage --reporter=junit --outputFile=report.xml
 
# 调试单个文件
vitest start --inspect-brk --no-file-parallelism src/foo.test.ts

与同类工具对比

vs Jest：无 babel 转换开销、启动快、原生 ESM/TS；Jest 生态（snapshot/expect API）基本兼容
vs README 内置 bun test：bun 更快但生态与报告能力弱，vitest 的 UI/coverage/browser mode 更完整

zhaoweiguo 的知识库

目录