实战干货 | Vitest最佳实践(14分钟读完)

我见过太多人因为没搞懂 Vitest 的配置细节，导致单元测试跑起来像噩梦。就拿我最近接手的一个 Vue 项目来说，原本用 Jest 做测试，启动时间慢得离谱，还经常出莫名其妙的错误。换成 Vitest 后，直接把测试启动时间从 15 分钟砍到 3 分钟以内，效果立竿见影。你会发现它对 Vue 3 的支持特别细致，尤其是对组合式 API 的 mock 比起 Jest 容易多了。不过别以为它就是万能的，它对 Node.js 模块的处理还存在一些边界，得自己想办法绕过去。关键点在于配置项和测试策略，早点把这些踩出来的坑填上，省得后面反复折腾。

Vitest 的配置主要集中在 vitest.config.js 文件里，这个文件是项目的核心测试枢纽。我真正用起来发现，它不像 Jest 那么臃肿，配置项更精简，比如测试环境配置直接写成 env: 'test'，而不用一堆全局变量。如果你是 Vue 3 项目，必须在配置里加上 setupFiles: ['./setupTests.js']，否则组合式 API 的 setup 函数不会被正确加载。还有一个地方特别容易出错，就是在 testPathIgnorePatterns 配置里，不能用通配符，必须写死路径，否则会被 Vitest 误判执行范围。

实际操作中，大部分项目都会用到 tsconfig.json 和 jest.config.js 的迁移工作。我之前遇到一个案例，项目原本是用 Jest 写的 TS 测试，迁移到 Vitest 的时候，没注意 tsconfig.json 里的 resolveJsonModule 设置，导致测试文件里引用 JSON 数据时出错。解决办法是手动修改 tsconfig.json，把 resolveJsonModule 设置成 true，然后重新启动测试。另外，Vitest 的默认测试文件扩展名是 .spec.ts 或 .test.ts，不能直接写 .ts 文件，否则会被忽略。这个需要在配置里显式声明。

在 CI/CD 环境里，我尽量用默认配置，但有时候还是得调整。比如在 GitHub Actions 里，如果测试目录结构不一致，就容易出现找不到测试文件的情况。这时候得在测试命令里加上 --testPathPattern 参数，指定要运行的测试文件路径。比如 npx vitest --testPathPattern 'src//.{spec,test}.ts'。这个参数有时候能救命，尤其是当项目结构复杂到一堆嵌套目录的时候。还有个点是，如果你用的是 Vite 的 devServer，那它默认会加载模块里的所有内容，包括第三方库，这可能会让测试变得特别慢，这时候要配合 --noAutoImport 所在配置。

测试工具的稳定性有时候比配置更重要，尤其是 Vitest 在 Node.js 环境下的表现。我之前在某个云端 CI 服务上运行测试，发现 Vite 的默认 Node.js 环境版本太老，导致测试用例执行时出现不一致的问题。解决办法是手动指定 Node.js 版本，比如在 package.json 里写上 "engines": { "node": "20.x" }，或者在测试命令里加 --node-version 参数。不过这类操作需要在团队内部统一标准，不然每个成员的环境差异可能引发测试通过率不稳定的问题。

Vitest 有个很棒的功能是并行执行测试，这在处理大量测试用例时特别有用。但我的经验是，默认的并行策略有时候不够智能，尤其是当测试用例之间存在依赖关系的时候。比如我做过一个测试用例要做数据库操作，结果 Vitest 把它和其他用例并行执行了，导致数据混乱。解决办法是用 test.concurrent 标记那些可以并行执行的用例，同时在用例里用 beforeEach 或 beforeAll 来隔离环境。或者，你可以用 --runMode parallel 参数，但最好还是控制好用例之间的依赖关系。

Vitest 的 mock 函数支持比 Jest 更强，尤其是对 Promise 的处理。有一次我写了一个测试用例，mock 了一个返回 Promise 的 API，结果发现 Vitest 会自动 resolve 这个 Promise，让我误以为它执行成功了。后来才明白，得用 mockResolvedValue 去 mock Promise，而不是直接赋值。此外，Vitest 还支持 mock 函数的参数捕获，比如在 mock 函数里加上 mockImplementation(() => {})，就能记录调用时的参数，这个在调试时特别有用。

Vitest 在浏览器环境下的测试执行速度比 Jest 快很多，尤其是在处理大型组件的时候。我测试过某个 Vue 3 项目，使用 Vitest 在浏览器环境运行组件测试，每个测试用例平均执行时间是 Jest 的 60%，而且内存占用也更低。但有个问题是，Vitest 默认不支持像 Jest 那样用 jest.spyOn 来 mock 方法，得用 vitest.spyOn 或者 vitest.mock 来替代。这部分 API 有时会让人感觉不够顺手，尤其是对习惯了 Jest 的人来说。

虽然 Vitest 在测试方面表现优秀，但它的局限性也不容忽视。比如在处理异步操作时，Vitest 的自动等待策略有时候不够灵活。有一次我写了一个测试用例，里面有个异步请求，结果 Vitest 没有正确等待请求完成就断言结果，导致测试失败。后来发现是因为这个请求用了自定义的 fetch 函数，而 Vitest 默认的测试环境没有这个函数的 mock。解决办法是手动在 setupTests.js 里定义 mock，或者用 vitest.mock 来覆盖相关模块。这种边角情况还挺多的。

Vitest 的覆盖率工具也挺实用，但它的默认配置有时候太保守了。我之前用 coverage 选项跑测试，发现它没有覆盖到像 TypeScript 类里面的私有方法，这部分需要手动配置 coverage 相关的参数。比如在 vitest.config.js 里加上 coverage: { include: ['src//.ts', 'src//.vue'] }，或者设置 exclude 来排除不需要覆盖的文件。另外，Vitest 的覆盖率报告默认是 JSON 格式，如果要生成 HTML 报告，得用 coverage.reporter 参数指定为 html。这种方式比 Jest 的覆盖率更直观。

在文件结构上，Vitest 的测试文件命名规则也特别严格。它要求测试文件必须以 .spec.js 或 .test.js 结尾，否则不会被识别。我之前有个测试文件直接叫 login.js，后来总提示找不到测试文件，最后才发现是没加后缀。解决方法是统一给测试文件加上后缀，或者在配置里指定 testMatch。还有个地方容易出错，就是测试文件和源文件不能在同一个目录下，否则会有冲突。这时候就得用 testDir 参数来指定测试目录，比如配置成 'tests'，这样就不会出问题了。

Vitest 的测试套件支持也比 Jest 更灵活，尤其是它对测试用例分组的能力。我用过一次，把测试套件分成了多个文件，结果发现 Vitest 默认没有自动加载这些文件，得用 testDir 参数来指定目录，或者在配置文件中用 include 参数包含所有测试文件。不过如果项目文件结构复杂，还是推荐使用 glob 模式来指定文件路径，比如 'tests//.spec.ts' 这样。这样能避免遗漏测试文件，也能让测试运行更高效。

测试工具的实战体验需要结合项目实际情况来看，Vitest 的配置虽然简单，但有些边缘情况处理得不太完善。比如在处理异步函数时，默认的测试环境会自动等待 Promise 完成，但如果你用的是自定义的异步库，就必须手动处理。这时候，我通常会用 vitest.extend 来扩展测试环境，或者用 setup 函数来初始化相关依赖。这种方法虽然麻烦，但能确保测试的稳定性。

有时候，Vitest 的测试用例执行顺序会出问题，尤其是当测试目录结构有点乱的时候。有次我做了个测试套件，结果发现某些用例执行顺序错误，导致数据污染。后来才发现，是因为 Vitest 的测试用例加载器没有按顺序执行。这时候用 --testPathPattern 和 --runMode sequential 参数能控制顺序，但更稳妥的方法是用 setupFiles，把环境初始化统一处理。这种方法能避免测试用例之间互相影响，特别是涉及全局状态的时候。

Vitest 还有一个冷门但实用的功能，就是支持测试用例的并行执行。这个功能在处理大量测试文件时特别有用，能显著提升测试效率。但我的经验是，这种并行执行并不适合所有场景。比如，当测试用例需要访问共享资源时，必须用 beforeEach 或 beforeAll 来隔离环境。否则，测试结果可能会出现不一致。我曾经用过 --runMode parallel 参数，结果发现某些测试用例执行失败，后来才想到是资源冲突的问题。

如果项目里有大量 Node.js 模块，Vitest 的处理方式可能会带来一些问题。比如我之前做过一个 Node.js 项目的测试，发现 Vitest 没有正确加载某些模块，导致测试用例出错。这时候需要手动配置 vitest.config.js 里的 moduleDirectories，或者用 mock 模块来覆盖。我记得以前用过 mock 函数来替代某个模块的实现，这样就能绕过模块加载的问题。但这种方法有点侵入性，得谨慎使用。

Vitest 的测试用例执行速度确实比 Jest 快，但这也带来了某些限制。比如在处理一些复杂的异步操作时，它的自动等待策略有时候不够精准。我之前用过一个测试用例，里面有一些异步操作，结果 Vitest 把它们当成同步执行，导致测试结果不准确。后来发现是因为测试环境的配置问题，这时候需要手动调整测试用例的执行顺序，或者用 vitest.mock 来覆盖相关模块。

Vitest 的测试报告工具也值得一看，尤其是它支持的 HTML 报告。我之前用过一次，发现它的报告比 Jest 更清晰，特别是能展示测试用例的执行时间和覆盖率。不过这个功能也有些限制，比如报告生成需要额外的参数，或者某些环境不支持。这时候要么用 --coverage 参数直接生成报告，要么用 vitest.reporter 来指定生成方式。这种方法虽然简单，但需要确保所有测试用例都能正确生成报告。

最后，Vitest 的测试用例执行效率确实不错，但它的稳定性有时候还差一点。我之前用过一个测试用例，里面有个异步请求，结果 Vitest 把它当成同步执行，导致测试失败。后来才发现是因为测试环境没有正确处理 Promise。这时候需要手动调整测试用例的执行方式，或者用 vitest.mock 来覆盖相关模块。这些经验都是踩坑踩出来的，得记牢了。