Vitest 单元测试入门指南

本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。

直接回答：Vitest 是构建在 Vite 之上的轻量高速测试框架：原生 ESM 支持、提供watch反馈和大量Jest风格API，但语义并非完全相同——前端（Vite 项目）与 Node 后端都适用，是当前 JavaScript/TypeScript 新项目的首选测试方案之一。

为什么是 Vitest

Vitest复用Vite转换管线，支持按变更重跑。反馈耗时取决于套件与环境；Jest迁移仍需核对mock、快照、计时器、覆盖率及隔离差异，不能只替换导入就假设等价。

安装配置

mkdir vitest-demo && cd vitest-demo
npm init -y
npm install --save-dev vitest

package.json：

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

Vite 项目零配置复用 vite.config.ts；非 Vite 项目建一个 vitest.config.ts 即可。

第一个测试

sum.test.js：

import { describe, it, expect } from "vitest";
import { sum } from "./sum";

describe("sum", () => {
  it("1 + 2 等于 3", () => {
    expect(sum(1, 2)).toBe(3);
  });
});

一个常见区别：默认不注入全局 API，需要显式 import（也可以在配置里开 globals: true 完全对齐 Jest 习惯）。

运行与过滤

vitest run              # 单次（CI）
vitest                  # watch 模式
vitest run sum          # 按文件名过滤
vitest run -t "等于 3"  # 按用例名过滤

it.only / describe.only 临时聚焦，it.skip 跳过，it.todo 登记待写用例。

源码内嵌测试

Vitest 支持把测试写在源码文件里（Rust 风格）：

// sum.js
export function sum(a, b) {
  return a + b;
}

if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it("sum", () => {
    expect(sum(1, 2)).toBe(3);
  });
}

需在Vitest配置设置 test.includeSource（如 ['src/**/*.js']）才能收集；生产Vite构建还需 define: { 'import.meta.vitest': 'undefined' } 并启用树摇，才能消除相关分支，不能假设自动剔除。适合小型工具库；业务项目仍建议独立测试目录。

Mock

API 与 Jest 风格相近，具体mock提升与模块行为仍应查迁移说明：

import { vi } from "vitest";

vi.mock("./api");                        // 模块 Mock
const fn = vi.fn().mockReturnValue(42);  // Mock 函数
const spy = vi.spyOn(service, "fetch");  // 间谍
vi.useFakeTimers();                      // 假定时器
vi.setSystemTime(new Date("2026-01-01")); // 冻结时间

钩子

import { beforeAll, beforeEach, afterEach, afterAll, vi } from 'vitest';

beforeAll(() => { /* 套件前 */ });
beforeEach(() => { /* 每条前 */ });
afterEach(() => {
  vi.restoreAllMocks();
  vi.useRealTimers();
});
afterAll(() => { /* 套件后 */ });

覆盖率

npm install --save-dev @vitest/coverage-v8
vitest run --coverage

输出语句/分支/函数/行四维报告，HTML 报告可逐行查看未覆盖代码。

Vitest UI

npm install --save-dev @vitest/ui
vitest --ui

浏览器里查看用例树、实时重跑、检查控制台输出与模块依赖图——大套件导航体验极佳。

常见问题（FAQ）

Q：Vitest 能完全替代 Jest 吗？
A：可迁移许多场景，但功能兼容与运行速度需评估。少数依赖 Jest 特有生态（如某些 snapshot 序列化插件）的项目需要评估；Vite项目可优先评估，也需结合既有工具链选择。

Q：非 Vite 项目用 Vitest 划算吗？
A：划算。Vitest 独立可用，自带转换管线，Node 后端项目用它跑 TS 测试同样顺滑。

Q：测试里 import 的 CSS/图片怎么处理？
A：资源处理受环境（Node、jsdom、浏览器模式）及配置影响；按具体报错和所用Vitest主版本核对配置，不要照搬其他版本的server.deps或Jest transformer。

官方参考

• 官方文档 1
• 官方文档 2
• 官方文档 3

资料核对日期：2026-09-29。

延伸阅读

• Python unittest 模块入门指南