Vitest — 下一代测试框架
由 Vite 驱动的极速单元测试框架。原生 ESM、智能 Watch 模式、Jest 兼容 API,重新定义前端测试开发体验。
1. 项目背景
Vitest 由 Anthony Fu 和 VoidZero 团队于 2021 年创建,目标是解决前端测试领域的一个长期痛点:测试框架与构建工具的割裂。Jest 虽然生态成熟,但其基于 jest-runtime 的模块系统需要额外配置才能理解 TypeScript、ESM、JSX 等现代语法——而这些恰好是 Vite 天然支持的。
Vitest 的核心洞察:复用 Vite 的转换管道(transform pipeline)、解析器(resolver)和插件系统,零配置即可获得与开发环境一致的测试运行环境。这不仅消除了配置负担,更重要的是确保了测试行为与应用运行行为完全一致。
🪄 设计哲学
一个配置,两处运行。 你的 vite.config.ts 既用于开发/构建,也直接驱动测试——不需要 jest.config.js、babel.config.js 等叠加配置。
解决的问题:
- Jest 配置繁琐(TypeScript/ESM/CSS Modules 需要额外 transformer)
- Jest 启动慢(vitest 的 watch 模式利用 Vite 的 HMR 机制实现毫秒级重跑)
- 测试环境与开发环境不一致(不同的模块解析、不同的转换规则)
- 缺乏原生 ESM 支持(vitest 原生支持 top-level await、import.meta)
2. 快速上手
最小可运行示例——3 行代码开始测试:
import { expect, test } from 'vitest'
import { sum } from './sum'
test('adds 1 + 2 to equal 3', () => {
expect(sum(1, 2)).toBe(3)
})
常见场景:
import { vi, test, expect } from 'vitest'
import { fetchUser } from './api'
// Mock 一个模块
vi.mock('./api', () => ({
fetchUser: vi.fn(() => Promise.resolve({ name: 'Alice' }))
}))
test('mock example', async () => {
const user = await fetchUser(1)
expect(user.name).toBe('Alice')
expect(fetchUser).toHaveBeenCalledWith(1)
})
import { expect, test } from 'vitest'
test('snapshot', () => {
const data = { id: 1, items: ['a', 'b', 'c'] }
expect(data).toMatchSnapshot()
})
3. 工程化方案
| 类别 | 工具 | 配置 |
|---|---|---|
| 包管理 | pnpm (v11) | pnpm-workspace.yaml — catalog 模式统一版本 |
| 构建 | Rollup + tsup | 每个子包独立 rollup.config.js |
| TypeScript | tsc + unplugin-isolated-decl | 项目级 tsconfig.json + 子包 tsconfig.json |
| Lint | ESLint (flat config) | @antfu/eslint-config + 根目录 eslint.config.js |
| 测试 | Vitest 自身 | 自举测试——Vitest 用 Vitest 测试自己 |
| CI/CD | GitHub Actions | 多 Node 版本矩阵 + 浏览器测试 (Playwright) |
值得学习的工程化实践:
- Catalog 模式:
pnpm-workspace.yaml中用catalog字段统一管理所有依赖版本,避免版本漂移 - Patch 管理:对上游依赖的修改通过
patches/目录 + pnpm 的patchedDependencies机制管理 - 自举测试:
test/目录下的集成测试使用 vitest 本身运行,保证发布质量 - 多构建产物:每个子包独立构建,通过
exports字段细粒度控制导出
4. 项目制品
| 包名 | npm | 职责 |
|---|---|---|
vitest | 主包 | CLI、配置、Node API、Browser API |
@vitest/runner | 内部 | 测试执行引擎(suite/test/钩子) |
@vitest/mocker | 内部 | 模块模拟系统(vi.mock / vi.spyOn) |
@vitest/expect | 内部 | 断言库(Jest + Chai 兼容) |
@vitest/spy | 内部 | Spy / Stub 实现 |
@vitest/snapshot | 内部 | 快照管理 |
@vitest/utils | 内部 | 工具函数、diff 算法、序列化 |
@vitest/ui | 可选 | Web UI 界面 |
@vitest/browser | 可选 | 浏览器模式核心 |
@vitest/coverage-v8 | 可选 | V8 原生覆盖率 |
@vitest/coverage-istanbul | 可选 | Istanbul 覆盖率 |
@vitest/browser-playwright | 可选 | Playwright 浏览器集成 |
@vitest/browser-webdriverio | 可选 | WebdriverIO 浏览器集成 |
@vitest/pretty-format | 内部 | 格式化输出(类 jest 的 pretty-format) |
@vitest/web-worker | 内部 | Web Worker 支持 |
5. 项目结构
6. 核心链路概览
6.1 一次完整测试运行的生命周期
- CLI 启动
packages/vitest/src/node/cli.ts→ 使用cac解析命令行参数 → 创建Vitest实例 - 配置解析
packages/vitest/src/node/core.ts:252→resolveConfig()合并 CLI 选项 + vite.config.ts + vitest 默认值 - Vite Server 创建
复用或创建 ViteDevServer → 注册 vitest 插件 → 配置模块解析 - 项目发现
resolveProjects()→ 扫描 workspace 中的 test projects → 创建TestProject实例 - 文件收集
VitestSpecifications→ 根据include/exclude模式找到测试文件 → AST 分析提取测试元数据 - Worker 池分配
ProcessPool→ 根据pool配置(threads/forks/vmThreads)创建 worker 进程 - 模块加载与转换
Worker 内通过 Vite 的SSR 模块图加载测试文件 → Vite 插件管道转换 TS/JSX/CSS - 测试执行
@vitest/runner→startTests()→ 按序执行 suite → beforeEach → test → afterEach - 结果报告
Reporter 管道 → 终端输出 / JSON / JUnit / HTML 报告
6.2 核心数据流
graph LR
A[CLI 参数] --> B[Vitest 实例]
B --> C[ViteDevServer]
B --> D[resolveConfig]
D --> E[TestProject x N]
E --> F[Worker Pool]
F --> G[Worker 进程]
G --> H[模块加载 via Vite SSR]
H --> I[@vitest/runner]
I --> J[Test Results]
J --> K[Reporter]
K --> L[终端/JSON/JUnit/HTML]
M[Mocker Plugin] -.-> H
N[Coverage Provider] -.-> I
图:Vitest 核心数据流 —— 从 CLI 到测试报告的完整链路
6.3 推荐阅读路径
- 1packages/vitest/src/node/cli.tsCLI 入口,创建 Vitest 实例
- 2packages/vitest/src/node/core.tsVitest 核心类:生命周期管理、配置、项目池
- 3packages/vitest/src/node/pool.tsWorker 线程/进程池管理
- 4packages/vitest/src/runtime/runBaseTests.tsWorker 内测试执行入口
- 5packages/runner/src/run.tsRunner 核心:startTests / 钩子 / 并发控制
- 6packages/runner/src/suite.tssuite/test API 定义与 task 构建
- 7packages/mocker/src/node/Mocker:Vite 插件拦截 + 自动 mock
6.4 关键代码速览
// ★ Vitest 核心类:整个测试运行器的中枢
export class Vitest {
public readonly version = version
public readonly logger: Logger
public readonly packageInstaller: VitestPackageInstaller
public readonly watcher: VitestWatcher
public projects: TestProject[] = []
public vcs: VCSProvider
// ★ 构造时仅做最基础的初始化
constructor(modeOrCliOptions, cliOptionsOrOptions?, maybeOptions?) {
this._cliOptions = cliOptions
this.logger = new Logger(this, options.stdout, options.stderr)
this.packageInstaller = options.packageInstaller || new VitestPackageInstaller()
this.specifications = new VitestSpecifications(this)
this.watcher = new VitestWatcher(this)
}
}
// ★ Runner 使用高性能计时器
const now = globalThis.performance
? globalThis.performance.now.bind(globalThis.performance)
: Date.now
const unixNow = Date.now
const { clearTimeout, setTimeout } = getSafeTimers()
7. 架构总图
graph TB
subgraph "Main Process (Node.js)"
CLI["cac CLI
cli.ts"]
V["Vitest 实例
core.ts (1707行)"]
CFG["resolveConfig
合并 vite 配置"]
VS["ViteDevServer
复用 Vite 插件体系"]
TP["TestProject × N
project.ts"]
SPEC["VitestSpecifications
文件发现 + AST"]
POOL["ProcessPool
Worker 管理"]
REP["Reporter 管道
终端/JUnit/JSON/Blob"]
end
subgraph "Worker Process"
WE["Worker 入口
runBaseTests.ts"]
VL["Vite SSR 模块加载
转换 TS/JSX/CSS"]
RUN["@vitest/runner
run.ts / suite.ts"]
MK["@vitest/mocker
vi.mock 拦截"]
EXP["@vitest/expect
断言匹配"]
SN["@vitest/snapshot
快照比对"]
end
subgraph "Browser"
BM["Browser Mode
Playwright / WebDriverIO"]
end
CLI --> V
V --> CFG
CFG --> VS
VS --> TP
TP --> SPEC
SPEC --> POOL
POOL --> WE
WE --> VL
VL --> RUN
MK -.-> VL
RUN --> EXP
RUN --> SN
RUN --> REP
BM -.-> WE
style V fill:#7c3aed,color:#fff
style RUN fill:#2563eb,color:#fff
style MK fill:#059669,color:#fff
图:Vitest 架构总图 —— 主进程、Worker 进程、浏览器模式三层协作
8. 模块深度导航
🏃 Runner 执行引擎
suite/test 定义、钩子系统、并发控制、重试机制、Around Hooks
核心🎭 Mocker 模块模拟
vi.mock/vi.spyOn、Vite 插件拦截、自动 mock、浏览器端 MSW 集成
核心✅ Expect 断言系统
Jest expect + Chai 双 API、非对称匹配器、自定义匹配器扩展
核心⚙️ Vitest 核心架构
CLI 入口、配置解析、Worker 池、Vite 集成、Reporter 管道
主包📸 Snapshot 快照系统
快照存储/比对/更新、内联快照、序列化器、环境适配
特性🌐 Browser 浏览器模式
Playwright/WebDriverIO 集成、iframe 沙箱、组件测试
特性9. 同类库对比
| 维度 | Vitest | Jest | Mocha |
|---|---|---|---|
| 配置复杂度 | 零配置(复用 Vite) | 需 babel/ts-jest | 需手动组装 |
| ESM 支持 | 原生 ESM first | 实验性支持 | 需额外配置 |
| Watch 模式 | HMR 级别(毫秒) | 基于文件变更 | 需插件 |
| 覆盖率 | V8 原生 + Istanbul | Istanbul | 需 nyc/c8 |
| 浏览器测试 | ✅ 原生支持 | ❌ jsdom 模拟 | ❌ 需 Karma |
| TypeScript | 开箱即用 | 需额外配置 | 需 ts-node |
| Monorepo | Workspace 原生 | projects 配置 | 需手动组织 |
| 兼容性 | Jest API 兼容 | — | 风格差异大 |
为什么基于 Vite 而不是自己实现模块加载?
复用 Vite 的转换管道意味着 Vitest 天然支持 Vite 生态中的所有插件和配置。这不是一个"偷懒"的决定,而是一个架构级的判断:测试框架不需要也不应该重新发明模块加载。这不仅减少了维护负担,更重要的是保证了测试环境与打包环境的行为一致性。
10. 学习要点总结
| 🏗️ 架构能力 | 学习价值 |
|---|---|
| Vite 插件体系复用 | 理解"组合优于继承"在构建工具中的实践 |
| Monorepo 架构 | 16 个包的职责划分、依赖管理、Catalog 模式 |
| Worker 进程池 | 多线程测试执行的隔离与通信 (birpc) |
| 插件化 Mocker | Vite 插件拦截 + 运行时反射的动态 mock 机制 |
| 双 API 兼容 | Jest expect + Chai 双接口的设计模式 |
| 浏览器模式 | iframe 沙箱 + CDP 协议 + WebSocket 通信 |
💡 一句话总结
Vitest 不是"更好的 Jest"——它是利用 Vite 生态系统重新思考测试框架的产物。它的最大创新不是某个具体功能,而是证明了 构建工具和测试框架可以共享同一条管道,从而消除了前端开发中"配置地狱"的最后一公里。