调试

TIP

调试测试时，你可能需要使用以下选项：

• --test-timeout=0 防止测试在断点处暂停时因超时而中断。
• --no-file-parallelism 禁用测试文件的并行运行，以确保调试的稳定性。

VS Code

在 VS Code 中，通过 JavaScript Debug Terminal 可以快速调试测试。打开一个新的 JavaScript Debug Terminal 并直接运行 npm run test 或 vitest 即可。此方法适用于在 Node.js 环境中运行的任何代码，因此也适用于大多数 JavaScript 测试框架。

你还可以添加专门的启动配置，以便在 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_internals>/**", "**/node_modules/**"],
      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
      "args": ["run", "${relativeFile}"],
      "smartStep": true,
      "console": "integratedTerminal"
    }
  ]
}

配置完成后，在调试选项卡中，确保已选中“Debug Current Test File”（调试当前测试文件）。接着打开需要调试的测试文件，按 F5 即可开始调试。

浏览器模式

要调试 Vitest 的浏览器模式，请在 CLI 中传递 --inspect 或 --inspect-brk 参数，或在 Vitest 配置中定义：

CLI

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

vitest.config.js

import { defineConfig } from 'vitest/config';

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

使用以下 VSCode 复合配置 来启动 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 运行配置。使用以下设置在调试模式下运行所有测试：

设置	值
工作目录	/path/to/your-project-root

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

Node Inspector，例如 Chrome DevTools

Vitest 也支持在不依赖 IDE 的情况下调试测试。但是，这要求测试不能并行执行。使用以下命令之一来启动 Vitest：

# 在单个工作线程中运行
vitest --inspect-brk --pool threads --poolOptions.threads.singleThread

# 在单个子进程中运行
vitest --inspect-brk --pool forks --poolOptions.forks.singleFork

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

如果你使用的是 Vitest 1.1 或更高版本，你也可以只提供 --no-file-parallelism 标志：

# 如果池类型未知
vitest --inspect-brk --no-file-parallelism

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

在观察模式下，通过使用 --poolOptions.threads.isolate false 选项，你可以在测试重新运行时保持调试器打开。