Vitest 现代前端单元测试框架技术调研

Vitest 是由 Vite 驱动的现代单元测试框架，与 Vite 共享配置、插件和转换管道，提供 Jest 兼容 API 的同时具备更快的冷启动与 HMR 式测试重跑。Vitest 4 将 Browser Mode 定为稳定特性，支持在真实浏览器中运行组件测试，是 Vite 生态项目的首选测试方案。

一、 基本信息

二、 技术定位与简介

Vitest 专为 Vite 项目 设计，解决 Jest 在 ESM、TypeScript、Vite alias 上的配置摩擦：

• Jest 兼容 API：describe、it、expect、vi.mock。
• Vite 原生：复用 vite.config.ts 的 resolve、plugins、alias。
• 极速反馈：watch 模式下增量重跑，接近 HMR 体验。
• ESM 优先：原生支持 import 与现代模块格式。
• Browser Mode：在 Playwright/WebdriverIO 驱动的真实浏览器中运行测试。
• Workspace：Monorepo 多项目测试编排。

适合 Vue、React、Svelte 等 Vite 技术栈的单元测试、集成测试与组件测试。

三、 快速上手安装说明

1. 安装

pnpm add -D vitest @vitest/ui

2. 配置 vitest.config.ts

import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    include: ['tests/**/*.{test,spec}.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
    },
  },
})

3. package.json 脚本

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:ui": "vitest --ui"
  }
}

4. 第一个测试

import { describe, it, expect } from 'vitest'
import { sum } from '@/utils/sum'
 
describe('sum', () => {
  it('adds two numbers', () => {
    expect(sum(1, 2)).toBe(3)
  })
})

5. Vue 组件测试

pnpm add -D @vue/test-utils happy-dom

import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'
import Button from '@/components/Button.vue'
 
describe('Button', () => {
  it('renders label', () => {
    const wrapper = mount(Button, { props: { label: 'Click' } })
    expect(wrapper.text()).toContain('Click')
  })
})

6. Browser Mode（Vitest 4+）

// vitest.config.ts
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})

// example.browser.test.ts
import { expect, test } from 'vitest'
import { render } from 'vitest-browser-vue'
import Component from './Component.vue'
 
test('renders in real browser', async () => {
  const screen = render(Component)
  await expect.element(screen.getByText('Hello')).toBeVisible()
})

四、 核心特性

1. Vite 配置复用

无需重复配置 alias、@/、PostCSS、Tailwind。

2. 智能 watch

仅重跑受影响的测试文件，速度极快。

3. 内联快照与 UI

@vitest/ui 提供可视化测试浏览器。

4. 模拟与时间

vi.mock、vi.fn、vi.useFakeTimers 与 Jest 类似。

5. 并发与分片

--pool=threads、--shard 加速 CI 大规模测试。

6. 覆盖率

内置 @vitest/coverage-v8 或 istanbul。

7. MSW 集成

与 MSW setupServer 无缝配合 API Mock。

8. Browser Mode

真实 DOM、CSS、浏览器 API，弥补 jsdom 不足。

五、 适用场景

1. 黄金适用场景

• Vite + Vue/React/Svelte 项目单元测试。
• Monorepo 多包测试（workspace 模式）。
• 需要快速 watch 反馈的日常开发。
• 组件测试（jsdom 或 Browser Mode）。
• 工具函数、hooks、状态逻辑测试。
• 与 MSW 结合的 API 层集成测试。

2. 局限适用场景

• Webpack 老项目（Jest 迁移成本高但可行）。
• E2E 全流程（用 Playwright/Cypress）。
• 非 JS 技术栈。
• 仅需极简测试（可能 bun:test 更轻）。

六、 技术亮点

1. 与 Vite 零摩擦

同一套配置服务开发与测试。

2. 速度

冷启动与 watch 重跑显著快于传统 Jest。

3. ESM 原生

避免 Jest + ESM 的常见坑。

4. Browser Mode 稳定

组件测试更接近真实用户环境。

5. 活跃生态

Vue、React、Nuxt、SvelteKit 官方推荐或默认集成。

七、 核心概念与架构

digraph Vitest_Architecture {
  rankdir=TB
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Config [label="vite.config / vitest.config", fillcolor="#bae6fd"]
  Vitest [label="Vitest Runner"]
  Pool [label="Test Pool\n(threads/forks)"]
  Env [label="Environment\n(node/jsdom/browser)"]
  Vite [label="Vite Transform Pipeline"]
  Tests [label="Test Files"]
 
  Config -> Vitest
  Vitest -> Pool
  Pool -> Env
  Vitest -> Vite
  Vite -> Tests
}

八、 技术局限与边界

1. Vite 绑定：非 Vite 项目收益降低。
2. jsdom 局限：部分浏览器 API 需 Browser Mode。
3. Jest 不完全兼容：少数 Jest API/快照格式差异。
4. Browser Mode 资源：比 jsdom 慢，需安装浏览器驱动。
5. 大型遗留 CJS 项目：迁移需处理模块格式。
6. UI 测试过度：应用 AGENTS 规则，展示组件默认不堆单测。

九、 生态地图

十、 生态集成

十一、 开发与工程化

1. 测试目录（本项目规范）

测试放 apps/tests/，镜像源码结构，导入使用 @/。

2. setup 文件

// vitest.setup.ts
import { server } from '@/mocks/server'
 
beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

3. CI 配置

- run: pnpm vitest run --coverage

4. 与 pnpm verify 集成

项目使用 pnpm verify 统一 lint、typecheck、test。

十二、 性能与安全

• pool: 'threads' 默认多线程，注意共享状态隔离。
• singleFork 选项处理原生模块问题。
• Mock 勿泄露真实 API 密钥到测试代码。
• Browser Mode CI 需缓存 Playwright 浏览器。
• --changed 仅跑 Git 变更相关测试加速 PR。

十三、 技术对比

十四、 最佳实践

1. Vite 项目默认选 Vitest，避免 Jest 双配置。
2. 稳定逻辑、纯函数、API 层优先单测；展示组件按项目规范克制。
3. API 测试配合 MSW，不依赖真实后端。
4. 使用 vitest.setup.ts 集中全局 mock。
5. CI 用 vitest run，本地用 vitest watch。
6. 需要真实 CSS/布局时用 Browser Mode。
7. Monorepo 用 test.projects 或 workspace 配置。
8. 覆盖率设合理阈值，避免为数字而写无意义测试。
9. vi.mock 注意 hoisting，优先 factory 形式。
10. 与 pnpm verify 保持一致的测试入口。

十五、 学习与社区资源

• 官方文档：https://vitest.dev/guide/
• Browser Mode：https://vitest.dev/guide/browser/
• GitHub：https://github.com/vitest-dev/vitest
• Discord：Vitest 官方社区