Vitest Test API 完全指南：test/it 定义、修饰符、参数化与 Fixtures 实战-北京尧图网络

AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载导读本文以 Vitest 5.x 为核心系统讲解test/it测试定义函数及其全部修饰符skip、only、todo、fails、concurrent、测试选项timeout、retry、tags、参数化测试test.each/test.for、Test Context 与自定义 Fixturesbuilder 模式的完整用法。内容基于本仓库 skills/vitest/references/core-test-api.md 展开并结合 features-context、features-test-tags、features-benchmarking 等配套文档深入解读 v4/v5 的 API 变化帮助读者写出结构清晰、可维护、可并发的 Vitest 测试套件。1. 基本用法test与it别名Vitest 提供与 Jest 兼容的测试定义 API。最基础的形式是从vitest包导入test传入测试名称与回调函数import { expect, test } from vitest test(adds numbers, () { expect(1 1).toBe(2) }) // 别名it import { it } from vitest it(works the same, () { expect(true).toBe(true) })it与test完全等价可混用。若测试文件配置了globals: true参见 core-config则无需导入即可直接使用test/it、expect等全局 API。函数名作为测试名如果将函数直接作为第一个参数传入Vitest 会使用该函数的名称作为测试名见 core-test-api.md 的 Key Pointstest(async () { // 函数名会被用作测试名 })无函数体的测试自动成为 todo当test()只给名字、不传回调时该测试会被标记为todo状态不运行、在报告中显示。2. 异步测试回调与 Promise 都会被自动 awaitVitest 原生支持async函数与返回 Promise 的回调无需手动调用donetest(async test, async () { const result await fetchData() expect(result).toBeDefined() }) // 返回 Promise 也会被自动等待 test(returns promise, () { return fetchData().then(result { expect(result).toBeDefined() }) })两种写法行为一致Vitest 会等待测试函数返回的 Promise 完成后再判定结果。3. 测试选项超时与重试每个测试可以附加执行选项。选项必须作为第二个参数传入——注意 v4 中第三个参数形式的 options 对象已被移除但紧随其后的尾随超时毫秒数仍然允许// Timeout默认5000ms test(slow test, async () { // ... }, 10_000) // 或者使用 options 对象 test(with options, { timeout: 10_000, retry: 2 }, async () { // ... })timeout该测试的超时毫秒数覆盖配置中的testTimeout默认 5000ms。retry失败后的重试次数覆盖配置中的retry。选项支持嵌套在describe中由父级继承在describe上设置的选项如timeout、retry、concurrent、tags会被其内部所有测试继承详见 core-describe。4. 测试修饰符Modifierstest对象上挂载了一系列修饰符方法用于控制测试的运行状态且可以链式组合。4.1 跳过测试test.skip/test.skipIf/test.runIftest.skip(skipped test, () { // 不会运行 }) // 条件跳过 / 条件运行 test.skipIf(process.env.CI)(not in CI, () {}) test.runIf(process.env.CI)(only in CI, () {}) // 通过上下文动态跳过 test(dynamic skip, ({ skip }) { skip(someCondition, reason) // ... })skipIf(condition)条件为真时跳过。runIf(condition)条件为真时才运行与skipIf语义互补。动态跳过从 Test Context 解构skip(condition?, message?)可在测试体内部根据运行时条件决定是否跳过跳过后测试显示为skipped状态并附带原因。4.2 聚焦测试test.onlytest.only(only this runs, () { // 文件中的其他测试会被跳过 })only用于调试时只跑指定测试。在 CI 环境中如果存在test.onlyVitest 会直接抛出错误除非在配置中显式开启// vitest.config.ts defineConfig({ test: { allowOnly: true, // 允许在 CI 中使用 .only }, })建议 CI 保持allowOnly关闭用失败来强制开发者移除误提交的.only。describe.only同理详见 features-filtering。4.3 待办测试test.todotest.todo(implement later) test.todo(with body, () { // 不会运行但会在报告中显示 })todo用于占位记录待实现的测试不执行函数体但在报告中可见相当于“未来的测试清单”。4.4 预期失败test.failstest.fails(expected to fail, () { expect(1).toBe(2) // 断言失败但测试通过 })fails表示“该测试预期失败”如果函数体抛错如断言失败测试反而通过如果函数体意外地没有抛错测试失败。适合标记已知缺陷、待修复的行为。4.5 并发测试test.concurrent// 并行运行 test.concurrent(test 1, async ({ expect }) { // 并发测试请使用 context.expect expect(await fetch1()).toBe(result) }) test.concurrent(test 2, async ({ expect }) { expect(await fetch2()).toBe(result) })注意两点并发测试中必须使用从 context 解构的expect即回调第一个参数中的{ expect }而不是顶层导入的expect。因为并发测试共享文件作用域context 绑定的expect才能保证断言与快照归属到正确的测试。concurrent只对真正 await 异步操作I/O、定时器的测试有加速效果纯同步测试仍会阻塞线程详见 features-concurrency。还可以用describe.concurrent让整个套件内的测试都并行见 core-describe或通过配置sequence.concurrent: true让所有测试默认并发。4.6 退出并发{ concurrent: false }test.sequential在 v5 中被移除。需要让某个测试退出继承来的并发或全局并发配置时使用选项形式test(must run alone, { concurrent: false }, async () {})典型场景describe.concurrent套件中有一个依赖共享状态的测试需要单独串行执行。describe.sequential同样已移除套件用describe(..., { concurrent: false }, ...)代替详见 features-concurrency。5. 参数化测试test.each与test.for参数化测试让同一组断言跑遍多组输入数据避免重复样板代码。5.1test.each数组、对象与模板字面量test.each([ [1, 1, 2], [1, 2, 3], [2, 1, 3], ])(add(%i, %i) %i, (a, b, expected) { expect(a b).toBe(expected) }) // 对象形式 test.each([ { a: 1, b: 1, expected: 2 }, { a: 1, b: 2, expected: 3 }, ])(add($a, $b) $expected, ({ a, b, expected }) { expect(a b).toBe(expected) }) // 模板字面量形式tagged template test.each a | b | expected ${1} | ${1} | ${2} ${1} | ${2} | ${3} (add($a, $b) $expected, ({ a, b, expected }) { expect(a b).toBe(expected) })三种形式分别对应数组解构、对象属性、以及标签模板字面量的行内表格数据按团队偏好选用。5.2test.for推荐优先使用test.for是比.each更推荐的形式——它不会展开spread数组回调的第二个参数直接是 TestContexttest.for([ [1, 1, 2], [1, 2, 3], ])(add(%i, %i) %i, ([a, b, expected], { expect }) { // 第二个参数是 TestContext expect(a b).toBe(expected) })v5 标题格式化变化标题使用pretty-format格式化通过$占位符插值的字符串不再加引号case $id会显示为case a1而不是case a1。插值值的长度受taskTitleValueFormatTruncate限制默认截断长度为 40。6. Test Context测试回调的第一参数每个测试回调的第一个参数都提供一组上下文工具test(with context, ({ expect, skip, task, signal, annotate }) { console.log(task.name) // 测试元数据 skip(someCondition, reason) // 动态跳过 expect(1).toBe(1) // 绑定到本测试的 expect })内置上下文属性一览详见 features-context属性说明task测试元数据name、file 等只读expect绑定到当前测试的expect并发测试的断言与快照必须用它skip(condition?, message?)动态跳过测试signal3.2AbortSignal在超时 / 取消 / bail 时触发 abortannotate(message, type?, attachment?)3.2附加报告器显示的注释onTestFinished(fn)/onTestFailed(fn)测试级清理 / 失败处理器benchv5基准测试 fixture仅在*.bench.ts文件中可用6.1signal在超时/取消时中止请求3.2// signal 在超时/取消/bail 时会被 abort test(aborts on timeout, async ({ signal }) { await fetch(/resource, { signal }) }, 2000)把signal传给fetch或其他支持AbortSignal的 API可以在测试超时或被取消时自动中止底层网络请求避免悬挂资源。6.2annotate给报告附加说明3.2test(annotated, async ({ annotate }) { await annotate(see issue #123, issues) })annotate附加的注释会由报告器展示可用于关联 issue、附上调试信息或说明测试意图。7. 自定义 Fixturesbuilder 模式4.1 推荐当多个测试需要共享初始化逻辑数据库连接、服务器实例等时用test.extend定义自定义 fixture。推荐使用 builder 模式因为类型可以自动推断并通过onCleanup完成清理import { test as base } from vitest const test base .extend(db, async ({}, { onCleanup }) { const db await createDb() onCleanup(() db.close()) // 在测试/作用域结束后运行 return db }) test(query, async ({ db }) { const users await db.query(SELECT * FROM users) expect(users).toBeDefined() })关键设计点.extend(name, options?, fixture)自动推断类型fixture 函数第一个参数可解构此前已定义的 fixtures第二个参数提供onCleanup。onCleanup每个 fixture 只能调用一次需要清理多个资源时应拆分为多个 fixture。Fixtures 是懒加载的只有被测试解构使用时才会初始化务必解构{ db }而不是访问context.db。作用域scope默认test每个测试一次可以用{ scope: file }每文件一次、{ scope: worker }每 worker 进程一次用于昂贵共享资源。只有test作用域的 fixture 能访问内置 contexttask、expect等。fixture 选项{ auto: true }表示每个测试自动运行{ injected: true }表示可通过项目配置provide覆盖。test.override4.1在某个 suite 及其子级中替换 fixture 值取代已废弃的test.scoped不能引入新 fixture 或修改scope/auto。Playwright 兼容的对象语法使用use()回调但类型需手动声明。更完整的 fixture 作用域表格、对象语法、injected fixtures 与test.override示例参见 features-context。8. 重试配置单值或高级对象重试不仅可通过 CLI--retry n全局指定也可以在单个测试上精细化配置test(flaky test, { retry: 3 }, async () { // 失败后最多重试 3 次 }) // 高级重试选项 test(with delay, { retry: { count: 3, delay: 1000, condition: /timeout/i, // 仅在匹配 timeout 类错误时重试 }, }, async () {})高级retry对象包含count最大重试次数delay每次重试前的延迟毫秒数condition可传正则或函数仅当错误满足条件时才重试例如只对timeout类错误重试避免掩盖真正的业务断言失败。CLI 层面还可配合 v5 的--repeats n把每个测试重复运行 n 次来排查偶现flaky问题见 core-cli。9. 测试标签 Tags4.1Tags 用于给跨文件的测试类别打标签从而按语义筛选运行并为某类测试统一应用共享选项timeout、retry。标签必须先在配置中声明然后应用到测试上4.1test(database test, { tags: [db, slow] }, async () {}) // 用标签表达式运行 // vitest --tagsFilter db !flaky声明与筛选的完整规则详见 features-test-tags必须声明未在配置中声明的标签会抛错除非strictTags: false。每个标签可携带timeout、retry、description、priority等选项应用到所有标记了它的测试。继承测试标签继承自父级describe文件顶部 JSDocmodule-tag会应用到文件内所有测试。冲突解决多个标签设置了同一选项时priority数值小者优先先于数组顺序测试自身选项始终胜出。筛选语法vitest --tagsFilter db !flaky、(unit || e2e) !slow、api/*通配符支持/||/!/()分组优先级notandor。多个--tagsFilter参数按 AND 组合。vitest --list-tags列出已声明标签。类型安全可通过declare module vitest { interface TestTags { ... } }增强标签名字面量类型。10. 基准测试 Benchmarksv5 重大变化v5 中bench不再是顶层导入而是作为 test-context fixture 在test()内部使用且文件必须匹配benchmark.include默认如**/*.bench.ts// 文件名需匹配 benchmark.include例如 *.bench.ts test(sort, async ({ bench }) { await bench(Array.sort, () [3, 1, 2].sort()).run() })bench()负责注册.run()负责执行并返回结果可通过断言结果如result.throughput.mean验证性能阈值。运行方式vitest bench只跑基准benchmark: { enabled: true }可与普通测试并存。迁移要点v5 移除了bench.skip/only/todo改用外层test.skip/only/todobenchmark.reporters、--compare、--outputJson等已移除改用--reporterjson --outputFile详见 features-benchmarking。11. Key Points 速查以下是本指南的核心结论也是 v4/v5 兼容性检查清单选项作为第二个参数传入v4 起第三个参数形式的 options 对象已移除尾随的 timeout 数字仍然允许。无函数体的测试自动标记为todo。test.only在 CI 中抛错除非配置allowOnly: true。并发测试与快照请使用 context 的expecttest.concurrent回调第一参数解构。函数名用作测试名第一个参数传函数时取其函数名。test.sequential已在 v5 移除用{ concurrent: false }退出继承或全局并发。test.fails用于预期失败的断言test.todo用于占位待办。参数化优先用test.for不解构数组、第二参数即 TestContexttest.each支持数组/对象/模板字面量三种形式。自定义 fixture 优先 builder 模式.extend类型自动推断、onCleanup清理fixtures 懒加载仅在被解构时初始化。Tags 必须先声明后使用CLI 筛选用--tagsFilter不是--tags。v5 中bench是 test-context fixture不再是顶层导入。延伸阅读本仓库的 Vitest skill 还包含以下配套参考文档可与本文结合使用Test Context 与 Fixtures 完整指南fixture 作用域、test.override、Playwright 兼容对象语法、injected fixturesTest Tags 定义与筛选语法配置声明、module-tag、TestRunner.matchesTags运行时检查测试过滤与运行控制-t、--changed、--related、include/exclude并发与并行执行describe.concurrent、maxConcurrency、pool 配置、sharding基准测试 Benchmarkingbench.compare、baseline 存储回放、自定义 providerVitest 配置详解testTimeout、retry、allowOnly、sequence.concurrent等全局默认值CLI 命令行参考--tagsFilter、--retry、--repeats、vitest bench、vitest list等Describe APIdescribe.skipIf/runIf/only/todo/concurrent、套件选项继承赞分享AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载相关推荐Supabase 仓库实战Vitest Test API 深度解析——从 test/it 定义到参数化与上下文Supabase 仓库实战Vitest Test API 深度解析——从 test/it 定义到参数化与上下文本文基于 Supabase 仓库中的 Vite后端前端数据库CUPP开源密码画像字典生成器CUPP开源密码画像字典生成器 CUPP 是一款面向渗透测试者的开源密码画像字典生成工具。给出目标的名字、生日和宠物名它直接产出一份可投喂给破解工具的密码词渗透测试网络安全CLIJest Expect API 完全指南内置匹配器、修饰符与自定义扩展实战Jest Expect API 完全指南内置匹配器、修饰符与自定义扩展实战编写测试时我们几乎总需要校验某个值是否满足特定条件Jest 的 expect测试质量保障代码覆盖率开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Vitest Test API 完全指南：test/it 定义、修饰符、参数化与 Fixtures 实战

相关推荐

PyTorch强化学习实现六轴机械臂实时轨迹规划：从仿真到部署

Modbus协议原理与PLC通信实战：地址映射、RTU/TCP选型及七道防护

清华智能机器人课件47页：传感融合、导航与路径规划工程落地指南

更多资讯

风力机叶片缺陷检测数据集：3687张实拍图+VOC/YOLO双格式

ob10实战：从TNS配置到批量巡检的Oracle连接工具指南

Android Studio内置AI助手Gemini实战：小团队开发效率提升15%的落地经验

嘉兴家装地暖安装哪家公司做得好，杭州永耀环境工程实力参考

Flutter isolate_agents鸿蒙化适配实战：并发调度与消息传递的迁移

js-xlsx实战：Excel导入导出与日期精度避坑指南

今日更新

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？