第21章 Vitest 测试调试指南：VS Code 与浏览器模式配置

Debugging

调试测试时，建议使用以下选项：

• --test-timeout=0：防止在断点处暂停时测试超时
• --no-file-parallelism：防止测试文件并行运行

VS Code

官方 VS Code 扩展支持通过“Debug Tests”按钮调试测试。不过，Vitest 也提供了工具来定义自定义配置。

在 VS Code 中快速调试测试的方法是借助 JavaScript Debug Terminal。打开一个新的 JavaScript Debug Terminal，直接运行 npm run test 或 vitest。由于任何在 Node 中运行的代码都支持这种调试方式，因此它适用于大多数 JS 测试框架。

此外，你还可以添加专门的启动配置，以便在 VS Code 中调试特定的测试文件：

{
  // 更多信息请访问：https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Current Test File",
      "autoAttachChildProcesses": true,
      "skipFiles": ["/**", "**/node_modules/**"],
      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
      "args": ["run", "${relativeFile}"],
      "smartStep": true,
      "console": "integratedTerminal"
    }
  ]
}

然后，在 Debug 选项卡中确保选中了“Debug Current Test File”。接着打开你要调试的测试文件，按下 F5 即可开始调试。

浏览器模式

调试浏览器测试最简单的方式是使用官方 VS Code 扩展。

当然，你也可以通过 CLI 传入 --inspect 或 --inspect-brk，或在 Vitest 配置文件中定义它们：

CLI

在 vitest.config.js 中配置：

vitest --inspect-brk --browser --no-file-parallelism

或者在 TypeScript 配置文件中定义：

import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    inspectBrk: true,
    fileParallelism: false,
    browser: {
      provider: playwright(),
      instances: [{ browser: 'chromium' }]
    },
  },
})

默认情况下，Vitest 使用 9229 端口作为调试端口。你可以通过在 --inspect-brk 后指定值来覆盖该端口：

vitest --inspect-brk=127.0.0.1:3000 --browser --no-file-parallelism

使用以下 VS Code Compound 配置，即可启动 Vitest 并在浏览器中附加调试器：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run Vitest Browser",
      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
      "console": "integratedTerminal",
      "args": ["--inspect-brk", "--browser", "--no-file-parallelism"]
    },
    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach to Vitest Browser",
      "port": 9229
    }
  ],
  "compounds": [
    {
      "name": "Debug Vitest Browser",
      "configurations": ["Attach to Vitest Browser", "Run Vitest Browser"],
      "stopAll": true
    }
  ]
}

IntelliJ IDEA

创建一个 Vitest 运行配置。使用以下设置以调试模式运行所有测试：

Setting	Value
Working directory	/path/to/your-project-root

然后以调试模式运行此配置。IDE 会在编辑器中设置的 JS/TS 断点处暂停。

Node Inspector，例如 Chrome DevTools

Vitest 还支持在没有 IDE 的情况下调试测试。但这要求测试不并行运行。使用以下任一命令启动 Vitest：

# 在单个 worker 中运行
vitest --inspect-brk --no-file-parallelism

# 在浏览器模式下运行
vitest --inspect-brk --browser --no-file-parallelism

Vitest 启动后会暂停执行，等待你打开可以连接 Node.js Inspector 的开发工具。你可以使用 Chrome DevTools，在浏览器中打开 chrome://inspect 来实现连接。

在 watch 模式下，你可以使用 --isolate false 选项，在测试重新运行时保持调试器打开状态。