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