R524809
370 lines
15 KiB
Markdown
370 lines
15 KiB
Markdown
# Vitest 入门：快速理解并上手前端自动化测试
|
||
|
||
> 面向 Atlas Seller Kit 的学习文档。本文解释 Vitest 是什么、为什么前端项目选它，以及如何在 `apps/web` 中安装、配置并写出第一批测试：断言、生命周期、mock、React 组件测试与覆盖率。读完即可在项目里独立写单测。
|
||
|
||
## 1. 一句话理解 Vitest
|
||
|
||
**Vitest = 测试运行器 + 断言库 + mock 工具，三合一，且构建在 Vite 之上。**
|
||
|
||
一个测试文件只涉及三个 API，10 秒即可看懂结构：
|
||
|
||
```ts
|
||
import { describe, expect, it } from 'vitest';
|
||
|
||
describe('被测对象', () => {
|
||
it('某个行为', () => {
|
||
expect(1 + 1).toBe(2);
|
||
});
|
||
});
|
||
```
|
||
|
||
- `describe`：把一组相关测试分组；
|
||
- `it`（别名 `test`）：一条测试用例，失败即该用例不通过；
|
||
- `expect(实际值).断言(期望值)`：断言，全部断言通过用例才算通过。
|
||
|
||
运行器负责找到所有 `*.test.ts` 文件、执行、输出报告；断言库就是 `expect` 那一族方法；mock 工具是 `vi.*`，用来"替换掉"你不想在测试里真实执行的依赖（网络请求、定时器、localStorage 等）。
|
||
|
||
## 2. 为什么选 Vitest 而不是 Jest
|
||
|
||
Vitest 的 API 有意做成和 Jest 兼容（`describe/it/expect/vi`），从 Jest 迁移基本只改配置。差别在于底座：
|
||
|
||
| 维度 | Vitest | Jest |
|
||
|---|---|---|
|
||
| 构建/转换 | 复用 Vite 管线 | 自带转换器（需要额外配置 TS/JSX/别名） |
|
||
| `@` 别名、插件 | `vite.config.ts` 里已有的直接继承 | 要在 `jest.config` 里再抄一遍 |
|
||
| ESM / TS | 开箱即用，无需 `transform` 配置 | ESM 支持至今仍偏繁琐 |
|
||
| 冷启动与增量速度 | 快（与 dev server 同源，watch 模式只重跑受影响文件） | 相对慢 |
|
||
| 生态 | 与 Vite 生态（本项目技术栈）天然一致 | 生态最大，但多面向 webpack 时代 |
|
||
|
||
对本项目还有一条硬约束：`apps/web` 用的是 **Vite 8**，需要 **Vitest 4.1+**（Vite 8 支持自 4.1 引入；4.1 起 Vitest 直接使用项目里已安装的 Vite，版本天然对齐）。安装时不用刻意锁旧版，装最新稳定版即可。
|
||
|
||
## 3. 在 apps/web 中安装与配置
|
||
|
||
### 3.1 安装
|
||
|
||
```bash
|
||
cd apps/web
|
||
# 必装
|
||
pnpm add -D vitest
|
||
# 组件测试三件套（jsdom 提供 DOM 环境，后文 §8）
|
||
pnpm add -D jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom
|
||
# 覆盖率（后文 §9）
|
||
pnpm add -D @vitest/coverage-v8
|
||
```
|
||
|
||
### 3.2 配置：直接写在 vite.config.ts 里
|
||
|
||
Vitest 默认读取 `vite.config.ts`——这意味着 `@` 别名、React 插件**零配置直接继承**，这是选它的最大红利。只需加一个 `test` 字段：
|
||
|
||
```ts
|
||
/// <reference types="vitest/config" />
|
||
import { fileURLToPath, URL } from 'node:url';
|
||
import { defineConfig } from 'vite';
|
||
import react from '@vitejs/plugin-react';
|
||
|
||
export default defineConfig({
|
||
plugins: [react()],
|
||
resolve: {
|
||
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
|
||
},
|
||
server: {
|
||
/* …原有配置不动… */
|
||
},
|
||
test: {
|
||
// Web 项目统一用 jsdom，纯逻辑测试在 jsdom 里跑也完全没问题
|
||
environment: 'jsdom',
|
||
// 每次测试前加载的公共准备代码（jest-dom 扩展、polyfill），见 §8
|
||
setupFiles: ['./src/test/setup.ts'],
|
||
coverage: {
|
||
include: ['src/**'],
|
||
reporter: ['text', 'html'],
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
顶部那行 `/// <reference types="vitest/config" />` 是给 TypeScript 的类型提示，让 `test` 字段获得补全和类型检查，不影响运行。
|
||
|
||
> ⚠️ 不要另建 `vitest.config.ts`：一旦它存在，`vite.config.ts` 会被**整体忽略（不合并）**，`@` 别名就会在测试里失效。本项目统一用 vite.config.ts 的 `test` 字段。
|
||
|
||
### 3.3 添加 npm scripts
|
||
|
||
`apps/web/package.json`：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"test": "vitest",
|
||
"test:run": "vitest run",
|
||
"test:coverage": "vitest run --coverage"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `pnpm test`：watch 模式，改代码自动重跑相关测试，适合开发时一直开着；
|
||
- `pnpm test:run`：跑一遍就退出，适合 CI 和提交前检查。
|
||
|
||
monorepo 里从仓库根目录执行：
|
||
|
||
```bash
|
||
pnpm --filter @atlas/web test:run
|
||
```
|
||
|
||
## 4. 写第一个测试
|
||
|
||
### 4.1 文件放哪、叫什么
|
||
|
||
Vitest 默认扫描两类文件：
|
||
|
||
- 与被测文件同目录的 `*.test.ts(x)` / `*.spec.ts(x)`，如 `src/utils/format.test.ts`；
|
||
- `__tests__/` 目录下的测试文件。
|
||
|
||
**本项目约定：与被测文件同目录同名加 `.test`**，如 `api.ts` 的测试叫 `api.test.ts`。就近放置，改哪个文件一眼就能看到它的测试。
|
||
|
||
### 4.2 用项目里的真实函数练手
|
||
|
||
`src/services/api.ts` 的 `apiErrorMessage` 是纯函数、无副作用，非常适合第一个测试（`src/services/api.test.ts`）：
|
||
|
||
```ts
|
||
import { AxiosError } from 'axios';
|
||
import { describe, expect, it } from 'vitest';
|
||
import { apiErrorMessage } from '@/services/api';
|
||
|
||
describe('apiErrorMessage', () => {
|
||
it('Error 对象返回其 message', () => {
|
||
expect(apiErrorMessage(new Error('token 过期'))).toBe('token 过期');
|
||
});
|
||
|
||
it('字符串原样返回', () => {
|
||
expect(apiErrorMessage('boom')).toBe('boom');
|
||
});
|
||
|
||
it('HTTP 错误优先展示后端 error.message', () => {
|
||
const error = new AxiosError(
|
||
'Bad Request',
|
||
'ERR_BAD_REQUEST',
|
||
undefined,
|
||
undefined,
|
||
{ status: 400, data: { error: { message: '用户名已存在' } } } as never
|
||
);
|
||
expect(apiErrorMessage(error)).toBe('用户名已存在');
|
||
});
|
||
|
||
it('无响应体时展示状态码', () => {
|
||
const error = new AxiosError('Bad Request', 'ERR_BAD_REQUEST', undefined, undefined, {
|
||
status: 400,
|
||
} as never);
|
||
expect(apiErrorMessage(error)).toBe('请求失败（HTTP 400）');
|
||
});
|
||
});
|
||
```
|
||
|
||
运行 `pnpm test:run`，看到绿色 ✓ 即通过。故意把某个期望值改错再跑一次，观察失败报告——它会把实际值和期望值的差异打印出来，这是 Vitest 体验最好的部分之一。
|
||
|
||
## 5. 常用断言速查
|
||
|
||
| 断言 | 含义 |
|
||
|---|---|
|
||
| `toBe(x)` | 严格相等（`===`，适合原始值、同一引用） |
|
||
| `toEqual(x)` | 深度相等（对象/数组逐字段比较） |
|
||
| `toStrictEqual(x)` | 深度相等 + 检查 class 与 `undefined` 字段 |
|
||
| `toBeTruthy()` / `toBeFalsy()` | 真 / 假 |
|
||
| `toBeNull()` / `toBeUndefined()` / `toBeDefined()` | null / undefined / 非 undefined |
|
||
| `toContain(x)` | 包含（数组元素或字符串子串） |
|
||
| `toHaveLength(n)` | `.length` 等于 n |
|
||
| `toMatch(regex)` / `toMatchObject(obj)` | 匹配正则 / 部分字段匹配 |
|
||
| `toThrow(msg?)` | 抛出异常 |
|
||
| `toHaveBeenCalledWith(...)` | mock 函数以指定参数被调用（§7） |
|
||
|
||
两个惯用法：
|
||
|
||
```ts
|
||
// 异步断言：await + resolves/rejects
|
||
await expect(authApi.login(payload)).rejects.toThrow();
|
||
|
||
// 取反：任意断言前加 .not
|
||
expect(list).not.toContain('deleted');
|
||
```
|
||
|
||
## 6. 生命周期与批量用例
|
||
|
||
```ts
|
||
import { beforeEach, describe, it } from 'vitest';
|
||
|
||
describe('购物车', () => {
|
||
// 每条 it 前执行：适合"重置状态"，保证用例互不影响
|
||
beforeEach(() => {
|
||
localStorage.clear();
|
||
});
|
||
|
||
// 同族还有 afterAll / beforeAll / afterEach，作用域限定在当前 describe 内
|
||
it('加入商品', () => { /* … */ });
|
||
it('移除商品', () => { /* … */ });
|
||
});
|
||
```
|
||
|
||
同一段逻辑测多组输入用 `it.each`，避免复制粘贴：
|
||
|
||
```ts
|
||
it.each([
|
||
['admin', true],
|
||
['', false],
|
||
[null, false],
|
||
])('isValidRole(%s) → %s', (role, expected) => {
|
||
expect(isValidRole(role)).toBe(expected);
|
||
});
|
||
```
|
||
|
||
## 7. Mock：隔离依赖的三种姿势
|
||
|
||
测试的核心纪律是**只测当前单元的逻辑，把外部依赖换成假的**。`vi` 提供三个层级的工具：
|
||
|
||
### 7.1 `vi.fn()`：造一个可断言的假函数
|
||
|
||
```ts
|
||
const onSuccess = vi.fn();
|
||
handle({ onSuccess });
|
||
expect(onSuccess).toHaveBeenCalledOnce();
|
||
expect(onSuccess).toHaveBeenCalledWith(expect.objectContaining({ id: 'p1' }));
|
||
```
|
||
|
||
### 7.2 `vi.mock()`：整个模块替换掉（最常用）
|
||
|
||
测试 `authApi` 时不应真的发 HTTP 请求，把 `@/services/api` 整体换掉：
|
||
|
||
```ts
|
||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||
import { authApi } from '@/services/auth';
|
||
import { api } from '@/services/api';
|
||
|
||
// 工厂函数返回"假模块"：auth.ts 只导入了 api，替换它即可
|
||
vi.mock('@/services/api', () => ({
|
||
api: { post: vi.fn(), get: vi.fn(), patch: vi.fn(), delete: vi.fn() },
|
||
}));
|
||
|
||
const mockedPost = vi.mocked(api.post);
|
||
|
||
describe('authApi', () => {
|
||
beforeEach(() => {
|
||
vi.clearAllMocks(); // 每条用例前清空调用记录，防止互相污染
|
||
});
|
||
|
||
it('logout 调用 POST /auth/logout', async () => {
|
||
mockedPost.mockResolvedValueOnce(undefined);
|
||
|
||
await authApi.logout();
|
||
|
||
expect(api.post).toHaveBeenCalledWith('/auth/logout');
|
||
});
|
||
});
|
||
```
|
||
|
||
两个关键机制：
|
||
|
||
- **提升（hoisting）**：`vi.mock` 调用会被提升到文件最顶部，先于任何 import 生效，所以"先 import 后 mock"的写法是安全的；但代价是**工厂函数里不能引用外部变量**（会报错），确有需要用 `vi.hoisted()` 声明。
|
||
- `vi.mocked(api.post)` 只是给类型加了 mock 能力，指向的就是假模块里的那个 `vi.fn()`。
|
||
|
||
### 7.3 `vi.spyOn`：只监听（或临时替换）对象上的某个方法
|
||
|
||
```ts
|
||
const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||
// …执行会打日志的代码…
|
||
expect(spy).toHaveBeenCalled();
|
||
spy.mockRestore(); // 还原，避免影响其他用例
|
||
```
|
||
|
||
其他高频工具一行记：
|
||
|
||
```ts
|
||
vi.useFakeTimers(); // 冻结时间，setTimeout/Date 可控（记得配 vi.useRealTimers() 还原）
|
||
vi.stubGlobal('fetch', vi.fn()); // 替换全局对象（fetch、localStorage 等）
|
||
```
|
||
|
||
## 8. 测试 React 组件
|
||
|
||
组件测试用 Testing Library：**像用户一样操作页面（渲染→点击→断言看到的内容），而不是断言内部状态**。它在 jsdom 里渲染真实 React 组件（React 19 需要 `@testing-library/react` ≥ 16，安装最新版即可）。
|
||
|
||
公共准备代码 `src/test/setup.ts`（对应 §3.2 的 `setupFiles`）：
|
||
|
||
```ts
|
||
import '@testing-library/jest-dom/vitest'; // 提供 toBeInTheDocument 等DOM断言
|
||
|
||
// antd 依赖 matchMedia，jsdom 未实现，需打桩
|
||
window.matchMedia ??= ((query: string) => ({
|
||
matches: false,
|
||
media: query,
|
||
addEventListener: () => {},
|
||
removeEventListener: () => {},
|
||
})) as typeof window.matchMedia;
|
||
```
|
||
|
||
一个组件测试的样子：
|
||
|
||
```tsx
|
||
import { render, screen } from '@testing-library/react';
|
||
import userEvent from '@testing-library/user-event';
|
||
import { describe, expect, it, vi } from 'vitest';
|
||
|
||
function ConfirmButton({ onConfirm }: { onConfirm: () => void }) {
|
||
return <button onClick={onConfirm}>确认删除</button>;
|
||
}
|
||
|
||
describe('ConfirmButton', () => {
|
||
it('点击后触发 onConfirm', async () => {
|
||
const onConfirm = vi.fn();
|
||
render(<ConfirmButton onConfirm={onConfirm} />);
|
||
|
||
await userEvent.click(screen.getByRole('button', { name: '确认删除' }));
|
||
|
||
expect(onConfirm).toHaveBeenCalledOnce();
|
||
});
|
||
});
|
||
```
|
||
|
||
要点：
|
||
|
||
- `render` 渲染组件，`screen.getByRole/getByText/getByLabelText` 按用户视角查询元素（查不到会抛错，用 `queryBy*` 断言"不存在"）；
|
||
- `userEvent` 模拟真实交互（点击、输入），必须是 `await`；
|
||
- 测页面级组件（如 `LoginPage`）时，若内部用到 Router/Session 上下文，需要先包一层 Provider 或 mock 对应模块——这也是组件测试的主要成本所在，建议**只对关键交互路径写组件测试**。
|
||
|
||
## 9. 日常运行与覆盖率
|
||
|
||
```bash
|
||
pnpm test # watch 模式（开发时开着）
|
||
pnpm test:run # 单次运行
|
||
pnpm test:run src/services # 只跑路径匹配的文件
|
||
pnpm test:run -t 'logout' # 只跑名字含 logout 的用例
|
||
pnpm test:run --related # 只测本次 git 变更涉及的文件（提交前自查很好用）
|
||
pnpm test:coverage # 覆盖率报告（终端表格 + html/coverage/index.html）
|
||
pnpm test -- --ui # 浏览器图形界面（需 pnpm add -D @vitest/ui）
|
||
```
|
||
|
||
覆盖率数字只是参考：`utils`、`services` 这类逻辑层应追求高覆盖；UI 组件靠少量关键交互测试兜底即可，不必为数字凑行数。
|
||
|
||
## 10. 在本项目的落地建议
|
||
|
||
1. **优先测两层**：`src/utils/` 纯函数（成本最低、收益最高）；`src/services/` 服务层——mock 掉 `@/services/api` 后，401 刷新重放、信封解包（`unwrapEnvelope`）、`apiErrorMessage` 这些核心逻辑都能稳定验证。
|
||
2. **组件测试抓大放小**：登录/注册表单校验与提交、路由跳转等关键路径值得写；纯展示组件不强制。
|
||
3. **会话相关逻辑先打桩再测**：`api.ts` 刷新失败会执行 `window.location.assign('/login')`，jsdom 里 location 不可随意改写，测试时用 `vi.stubGlobal` 或把跳转逻辑抽成可注入的函数。
|
||
4. **接入流程**：本地开发开 `pnpm test`；提交前 `pnpm test:run --related`；CI 里跑 `test:coverage`。后续可在 `turbo.json` 中加 `test` 任务，实现根目录 `turbo run test` 一键跑全部 workspace。
|
||
5. **与 typecheck 分工**：`tsc` 管"类型对不对"，Vitest 管"行为对不对"，两者互补，提交前都跑。
|
||
|
||
## 11. 常见坑速查
|
||
|
||
| 症状 | 原因与解法 |
|
||
|---|---|
|
||
| 测试里 `@/...` 导入报错"找不到模块" | 建了 `vitest.config.ts` 导致 `vite.config.ts` 被整体忽略。删掉它，统一写在 `vite.config.ts` 的 `test` 字段（见 §3.2） |
|
||
| `vi.mock` 工厂里引用了外部变量报错 | `vi.mock` 会被提升到文件顶部，工厂不能闭包引用外部变量；需要共享值时用 `vi.hoisted()` |
|
||
| antd 组件测试报 `matchMedia is not a function` | jsdom 未实现该 API，在 `src/test/setup.ts` 里打桩（见 §8） |
|
||
| `toBeInTheDocument` 类型报错 | 缺 `import '@testing-library/jest-dom/vitest'`，确认 setup 文件已配置 |
|
||
| 测 `setTimeout`/节流时用例"卡住"或时序不稳 | 用 `vi.useFakeTimers()` 冻结时间并手动 `vi.advanceTimersByTime()` |
|
||
| 覆盖率命令报错找不到 provider | 覆盖率是可选依赖：`pnpm add -D @vitest/coverage-v8` |
|
||
| 想让 `describe/it/expect` 免导入直接用 | 配置 `test.globals: true`，并在 tsconfig 的 `compilerOptions.types` 加 `"vitest/globals"`。本项目建议保持显式导入（不折腾 tsconfig，IDE 跳转也更准） |
|
||
|
||
## 12. 参考资料
|
||
|
||
- [Vitest 官方文档](https://vitest.dev/guide/)（Getting Started / Guide / API 三栏足够日常使用）
|
||
- [Vitest 4.1 发布公告](https://vitest.dev/blog/vitest-4-1.html)（Vite 8 支持与版本对齐说明）
|
||
- [Testing Library 官方文档](https://testing-library.com/docs/react-testing-library/intro/)（查询优先级与 userEvent 用法）
|
||
- 本项目接口契约：`docs/api/auth.md`、`docs/api/conventions.md`
|