VSCode调试Mocha异步测试的核心卡点是Node.js运行时、Mocha启动路径与sourceMap映射三者必须对齐；program须指向_mocha入口，args需含测试路径和--timeout，TS项目必配--require ts-node/register及正确sourceMap。
VSCode 调试 Mocha 异步测试，核心卡点不在语法或断点本身，而在 Node.js 运行时、Mocha 启动路径、sourceMap 映射三者是否对齐。只要其中一环错位，describe 报错、断点不命中、setTimeout 或 Promise 测试超时就必然出现。
“describe is not defined”错误的真正原因和修复方式
这不是 Mocha 没装好，而是 VSCode 调试器根本没加载 Mocha 的全局测试上下文（describe、it、beforeEach 等函数由 Mocha 注入全局作用域）。常见诱因：
- 直接运行
node test/*.spec.js—— Mocha 没参与执行，这些函数自然不存在 -
launch.json中program错写成测试文件路径（如"${file}"），而不是 Mocha 入口 - TypeScript 项目里漏了
--require ts-node/register，导致.ts文件被 Node 直接执行，而非经 ts-node 编译后交由 Mocha 托管
正确做法：确保 program 指向 ${workspaceFolder}/node_modules/mocha/bin/_mocha，且 args 第一项是测试文件路径（如 "${file}"）；TS 项目必须加 --require ts-node/register 到 args 列表里。
异步测试超时（timeout）必须显式配置的原因
Mocha 默认异步测试超时是 2000 毫秒，远低于实际网络请求、数据库操作或定时器场景所需时间。不改就会出现“测试绿了但逻辑没走完”或“断点刚 hit 就退出”的假象。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
- 所有
args配置中必须包含--timeout，推荐设为"5000"或更高（如"15000"） - 避免用
done()回调时忘记调用 —— 这会导致 Mocha 等待超时后强制 fail，而非报错提示 - 使用
async/await时，Mocha 会自动识别 Promise，无需done；但若混用（比如async it(...)里又手动调done()），会触发冲突警告
断点不命中？先查 sourceMap 和 outFiles 是否匹配
你在 src/index.ts 打的断点没反应，大概率不是 VSCode 问题，而是调试器加载的是编译后的 dist/index.js，但没找到对应的 dist/index.js.map，或映射路径指向了错误位置。
- TypeScript 项目必须在
tsconfig.json中开启"sourceMap": true，且"outDir"与"rootDir"设置合理（例如"outDir": "./dist"，"rootDir": "./src"） -
launch.json中需明确启用"sourceMaps": true，并设置"outFiles"匹配输出路径，如["${workspaceFolder}/dist/**/*.js"] - 测试文件（如
test/*.spec.ts）也得被tsconfig.json的"include"覆盖，否则不会生成对应 map - 修改代码后断点还停在旧逻辑？删掉
.ts-node缓存目录再试，或临时加"console": "integratedTerminal"看终端实际执行命令
本地安装 mocha 时 program 必须用 _mocha 而非 mocha 命令
VSCode 的 Node.js 调试器不继承 shell 的 PATH，所以写 "program": "mocha" 必然报 spawn mocha ENOENT。也不能依赖全局安装 —— 团队协作时版本不一致，CI 也可能失败。
- 永远用
"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha"（注意是_mocha，不是mocha） - Windows 用户不用管
.cmd后缀 ——_mocha是 JS 入口，跨平台稳定 - 如果用了 ESM（
"type": "module"），需额外加"runtimeArgs": ["--loader", "ts-node/esm"]，否则import会报错 - 别在
env里手动加NODE_OPTIONS=--inspect—— VSCode 已自动注入，重复会导致端口冲突
最易被忽略的是：_mocha 是一个可执行 JS 文件，不是 CLI 命令包装器；它绕过 shell 解析，直接由 Node 加载，这才是调试稳定的底层保障。
