VSCode中Node环境配合Vitest UI直观跟踪测试用例流向

在使用 VSCode 进行测试时，点击 Run Test 按钮后完全没有反应——这一现象虽然常见，但多数开发者第一时间会误以为是“插件安装错误”，继而反复卸载重装、切换版本。实际上，问题的根源往往更底层：要么项目中缺少 vitest.config.ts 配置文件，要么 Vitest 并未在本地正确安装。

VSCode 点击 Run Test 无响应？先确认 vitest.config.ts 是否存在及本地安装状态

VSCode 的 Test Explorer UI（如 vitest-explorer）仅负责渲染按钮和转发命令，它不提供执行环境，也不会调用全局安装的 vitest。换句话说，按下插件按钮后，系统只是尝试启动一个本地的 vitest 进程，而该进程能否成功启动，取决于以下两个关键因素：

• 项目根目录下必须包含 vitest.config.ts，即使里面只有一行 export default {};——空配置也比没有配置强。许多开发者认为“从未配置过，应该不需要”，结果 Vitest 启动流程直接卡在第一步。
• 务必执行 npm install --save-dev vitest 在本地进行安装。全局安装的 vitest 插件无法被识别，即便全局安装成功，VSCode 也不会使用它。
• 修改配置文件后，VSCode 不会自动刷新测试列表。需要手动关闭侧边栏再重新打开，或者按 Ctrl+Shift+P 输入 Vitest: Restart Server 来重启服务。

单个 it 用例点击无效？检查 testMatch 是否覆盖到你的文件路径

另有一种情况：按钮可以点击，测试列表也能显示，但某个 it 用例就是无法进入执行状态。问题很可能出在 文件匹配规则 上。Vitest 默认只扫描 **/*.test.ts 和 **/*.spec.ts 两类文件。如果你将测试文件放在 src/__tests__/Button.test.ts 这样的路径下，就必须显式配置 testMatch: ['**/__tests__/**/*.test.ts']，否则 UI 面板中根本看不到这个 it。

• 不要混用 include 和 testMatch，它们的作用层级不同：testMatch 是第一道门槛，决定“哪些文件算测试文件”；include 只是对已匹配的文件进行二次过滤。
• Windows 系统下路径分隔符无需特殊处理，Vitest 内部已做了归一化，使用 / 或 \ 均可。
• 如果是 Vue 或 React 项目，还需要额外注册对应的插件，否则 it 里一旦出现 JSX 就会报 ReferenceError: React is not defined，根本进入不了执行阶段。

想跟踪测试执行流向？别依赖UI面板，直接查看终端输出并添加 --no-file-parallelism

Vitest 默认使用 worker 并行执行测试文件，这在日常开发中是有益的，但到了调试阶段就变成了障碍。VSCode 的调试器无法 attach 到子进程，断点基本失效，也无法看到真实的执行顺序。

若想观察单个 it 的执行流程、在哪一步卡住、哪个 beforeEach 先执行，就需要切换回单线程模式：

• 手动在终端中运行 npx vitest --no-file-parallelism --test-timeout=0，此时断点可以正常暂停，console.log 也能按顺序输出。
• VSCode 内置的“Debug Test”右键菜单通常不会传递这些参数，因此优先使用上述命令来验证逻辑通路，比在 UI 面板中反复点击更可靠。
• 另外注意 beforeAll / afterAll 的生命周期范围：它们并非每个 it 都重新执行一次，而是整个 describe 块共享一次。这一点在调试时很容易被忽略。

覆盖率数字忽高忽低？别相信状态栏百分比，那只是当前文件的局部值

VSCode 状态栏右下角的覆盖率数字，仅反映当前打开文件中被测到的行数比例，并非全量数据。很多人看到那个数字从 80% 跳到 50%，就开始怀疑测试写错了，实际上只是切换了不同的文件而已。

真正要查看整体覆盖率数据和缺口，需要打开 HTML 报告：coverage/index.html。另外有一个容易踩的坑：Coverage Gutters 插件默认只认 lcov.info 格式，但 Vitest 默认输出的是 coverage/vitest-coverage.json——格式不匹配，插件根本读不到数据。

• 解决方案之一：让 Vitest 输出兼容格式。运行 npx vitest --coverage --reporter=lcov 会生成 coverage/lcov.info，Coverage Gutters 就能正常工作了。
• 或者换用其他工具：Wallaby.js 原生支持 vitest-coverage.json，无需额外转换。
• 还要注意：watch 模式与覆盖率报告是互斥的。VSCode 中点击 Run Test 是单次执行，若想持续观察覆盖率变化，需要手动运行 npx vitest --coverage --watch，再配合 Coverage Gutters 刷新装饰。