vitest-docs

Vitest 5

此技能涵盖 https://vitest.dev/guide/ 上记录的 Vitest 5.x。它着重于与习惯用法不同的方面：令人惊讶的默认值、陷阱、已弃用的 API 以及文档推荐的模式。参考文件中的每个声明都以该声明来源的页面结尾。

如何导航

1. 阅读下面的快速规则。它们能捕获最常见的错误。
2. 根据末尾的表格，打开与任务匹配的一个参考文件。
3. 当代码使用 Jest API 或 Vitest 4 行为时，请先阅读 references/migration.md。

快速入门

// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { restoreMocks: true } })

// math.test.ts
import { expect, test } from 'vitest'

test.for([[1, 1, 2], [1, 2, 3]])('add(%i, %i) -> %i', ([a, b, expected]) => {
  expect(a + b).toBe(expected)
})

• 需要 Vite >= 6.4.0 和 Node.js >= 22.12.0。vite 是一个对等依赖。https://vitest.dev/guide/migration
• 在脚本、CI 和代理中运行 vitest run。单独的 vitest 会在终端中启动监视模式。https://vitest.dev/guide/learn/writing-tests-with-ai
• 将 .vitest/ 添加到 .gitignore。https://vitest.dev/guide

快速规则

编写测试

• globals 被禁用：从 vitest 导入 test、expect、vi。https://vitest.dev/config/globals
• 使用 test.for 进行参数化，而不是 test.each。https://vitest.dev/guide/learn/writing-tests
• 通过夹具和 test.extend('name', fn) 共享设置，并且始终对它们进行解构。https://vitest.dev/guide/test-context
• 从 beforeEach 返回一个清理函数，而不是编写一个匹配的 afterEach。https://vitest.dev/api/hooks
• 不使用 done 回调。使用异步测试。https://vitest.dev/api/test
• 测试在运行期间不进行类型检查。运行 tsc 或 vitest --typecheck.enabled。https://vitest.dev/guide/learn/writing-tests , https://vitest.dev/guide/cli
• 在并发测试中，使用来自上下文的 expect：async ({ expect }) => {}。https://vitest.dev/api/test

断言

• await 每个 .resolves、.rejects、expect.poll 和 toMatchFileSnapshot，否则测试将失败。https://vitest.dev/guide/migration
• 使用 expect.poll 或 vi.waitFor 进行轮询，切勿使用 setTimeout 休眠。https://vitest.dev/guide/recipes/wait-for
• 使用 expect.assert(x) 收窄类型。toBeDefined() 不会收窄。https://vitest.dev/guide/recipes/type-narrowing
• 快照不会在 CI 中写入。读取差异后使用 vitest -u 更新。https://vitest.dev/guide/snapshot

模拟

• 优先使用 vi.mock(import('./x.js')) 而非字符串：该路径会随文件移动而更新，并且工厂函数会进行类型检查。https://vitest.dev/api/vi
• 将 vi.mock 和 vi.hoisted 保持在模块顶层。在其他地方调用它们会抛出错误。https://vitest.dev/guide/migration
• 工厂函数返回每个导出，包括 default。https://vitest.dev/guide/migration/jest
• clearMocks 默认开启。添加 restoreMocks: true 以在每个测试后恢复间谍。https://vitest.dev/config/clearmocks , https://vitest.dev/guide/learn/mock-functions
• 特定参数的返回值：vi.when(fn).calledWith(1).thenReturn(x)。https://vitest.dev/guide/recipes/conditional-mocking
• 使用 vi.fn(class { ... }) 模拟类。https://vitest.dev/guide/mocking/classes
• 在其自身文件中调用的函数无法被模拟。https://vitest.dev/guide/mocking/modules

配置和运行

• vitest.config.* 会忽略 vite.config.*，除非你使用 mergeConfig 合并它们。https://vitest.dev/config
• 设置 include、exclude 或 reporters 会替换默认值。展开 configDefaults。https://vitest.dev/config/include
• 默认环境 node。自行安装 jsdom 或 happy-dom。https://vitest.dev/guide/environment
• 默认池 forks。对于原生模块和 process.chdir 保持此设置。https://vitest.dev/config/pool
• .only 会导致运行在 CI 中失败（参见 allowOnly）。https://vitest.dev/api/test
• -t 匹配由 ' > ' 连接的全名。https://vitest.dev/guide/filtering

旧模式

旧	当前
jest.fn、jest.mock、jest.requireActual	vi.fn、vi.mock、await vi.importActual
test.each 行展开为参数	test.for 配合解构的行和上下文
test.sequential、describe.sequential	{ concurrent: false }
import { bench } from 'vitest'	test() 内部的 bench 夹具
test.scoped	test.override
workspace	test.projects
toMatchTypeOf	toExtend
测试或 describe 内部的 vi.mock	顶层 vi.mock，或 vi.doMock
未等待的 .resolves 自动等待	await expect(p).resolves
toHaveTextContent(/regex/)	toMatchTextContent(/regex/)
stdout 上的 vitest --reporter=json	.vitest/json/output.json，或 stdout: true
vitest/environments、vitest/coverage	vitest/runtime、vitest/node

详细信息和完整列表：references/migration.md。

参考文件

文件	阅读它用于
references/writing-tests.md	测试选项、test.for、并发、夹具、钩子、设置文件、全局设置、标签、基准测试、源码内测试
references/assertions-and-snapshots.md	expect 陷阱、异步断言、轮询、类型收窄、模式匹配、自定义匹配器、快照、类型测试
references/mocking.md	模拟清理、vi.fn、vi.spyOn、vi.mock、类模拟、vi.when、假定时器、全局变量、环境、MSW、memfs
references/config-and-cli.md	配置解析、include、globals、环境、池、项目、CLI 过滤器、监视、报告器、分片
references/coverage.md	v8 和 istanbul、coverage.include、报告、阈值、忽略提示
references/debugging-and-performance.md	调试器设置、常见错误、依赖内联、CommonJS、性能分析、加速、禁用隔离
references/browser-mode.md	浏览器模式设置、实例、Playwright 提供者、定位器、expect.element、userEvent、组件测试、视觉和 ARIA 快照
references/migration.md	Vitest 4 到 5 的更改和移除、Jest 和 Mocha 映射、升级卫生

已爬取的页面：SOURCES.md。