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 刷新装饰。