Mocha 原生不支持在 describe 回调中使用 await import() 动态导入测试模块；正确做法是通过顶层静态导入 + 函数式测试套件导出，在 describe 中传入执行函数，从而兼容 ESM 并保持原有组织结构。
mocha 原生不支持在 describe 回调中使用 await import() 动态导入测试模块；正确做法是通过顶层静态导入 + 函数式测试套件导出，在 describe 中传入执行函数，从而兼容 esm 并保持原有组织结构。
在从 CommonJS 迁移至 ES 模块（ESM）的过程中，许多开发者尝试沿用熟悉的测试组织方式——将多个 .spec.js 文件按功能拆分，并在主测试入口中动态加载。例如，CommonJS 下可直接在 describe 块内调用 require('./unit/test.spec.js')，测试定义会立即执行并注册到当前作用域。然而，当改用 ESM 的 await import('./unit/test.spec.js') 时，Mocha 将无法识别其中的 it、describe 等全局测试声明，最终导致 0 passing (0ms) ——根本原因在于：ESM 动态导入返回的是一个 Promise，其模块执行时机与 Mocha 的同步测试发现阶段不匹配；且 Mocha v10+（含 ESM 支持）明确要求所有测试定义必须在模块求值（evaluation）阶段完成，而非异步回调中。
✅ 正确解决方案：顶层导入 + 函数封装测试套件
将每个测试文件重构为导出一个无参函数，该函数内部调用 it、describe 等 Mocha API；主测试文件则在顶层（非异步上下文）导入该函数，并将其作为回调传入 describe：
// ./unit/test.spec.js —— ESM 测试套件文件
export default function unitTestSuite() {
it('should assert equality', () => {
assert.strictEqual(1, 1);
});
it('should handle async operations', async () => {
const result = await Promise.resolve(42);
assert.strictEqual(result, 42);
});
}
// test/index.spec.js —— 主测试入口（ESM 格式，需 .mjs 后缀或 package.json 中 "type": "module"）
import unitSuite from './unit/test.spec.js';
import functionalSuite from './functional/test.spec.js';
describe('Unit tests', unitSuite);
describe('Functional tests', functionalSuite);
// 可继续添加更多套件...
⚠️ 关键注意事项：
- 不可在 describe 内部使用 await import()：这会导致测试定义延迟到异步微任务中执行，Mocha 已完成测试发现流程，故视作“无测试”。
- 必须使用顶层静态 import：确保模块在文件加载时即被解析并执行其导出函数（当该函数被 describe 调用时）。
- Node.js 版本要求 ≥ 14.8.0，且测试文件需以 .mjs 结尾，或在 package.json 中声明 "type": "module"。
- 若需条件加载（如仅在 CI 中运行某套件），可在顶层用同步逻辑控制是否调用 describe，但导入语句仍须位于顶层（ESM 规范禁止条件 import）。
这种模式不仅完全复刻了 CommonJS 下的模块化组织能力，还具备更好的类型推导支持（TypeScript 友好）、更清晰的作用域隔离，以及与现代构建工具（Vite、esbuild）的天然兼容性。本质上，它将“测试注册”显式建模为函数调用，而非依赖模块副作用，使测试结构更可预测、更易调试。
