Mocha 不支持在 describe 内部使用 await import() 动态加载测试模块，因其执行时机与 Mocha 的同步测试注册机制冲突；正确方案是采用顶层静态导入 + 函数式测试套件导出，确保测试用例被及时注册。
如何在 mocha 中正确使用 esm 动态导入加载测试模块？mocha 不支持在 `describe` 内部使用 `await import()` 动态加载测试模块，因其执行时机与 mocha 的同步测试注册机制冲突；正确方案是采用顶层静态导入 + 函数式测试套件导出，确保测试用例被及时注册。
在从 CommonJS 迁移至 ES 模块（ESM）的过程中，许多开发者尝试沿用原有模式——在 describe 块中通过 await import() 动态加载测试文件，例如：
describe('functional tests', async function() {
await import('./function/test.spec.js'); // ❌ 不生效：0 passing (0ms)
});
但该写法无法正常运行。原因在于：
- Mocha 在启动阶段即同步扫描并注册所有 describe/it 块；
- await import() 是异步操作，其内部的 it/describe 调用发生在 Mocha 完成测试发现（test discovery）之后，因此被完全忽略；
- ESM 的模块执行是延迟且单次的，动态导入不会“重放”测试定义逻辑。
✅ 正确解法：将测试套件封装为可调用函数，并通过顶层 import 同步引入后传入 describe
首先，重构你的测试文件（如 ./unit/test.spec.js），使其默认导出一个接收 describe 上下文的函数：
// ./unit/test.spec.js
export default function() {
it('does something', () => {
assert.equal(1, 1);
});
it('handles edge cases', () => {
assert.ok(true);
});
}
然后，在主测试入口文件（需为 .mjs 或 type: "module" 的 .js）中，使用顶层静态 import 并传入 describe：
// test/index.mjs
import unitSuite from './unit/test.spec.js';
import functionalSuite from './function/test.spec.js';
describe('unit tests', unitSuite);
describe('functional tests', functionalSuite);
// 可继续添加更多套件...
⚠️ 注意事项：
- 必须使用顶层 import（非 await import()），确保模块在 Mocha 解析阶段即执行并注册测试；
- 测试文件本身应为纯 ESM（含 export default），避免混合模块系统；
- Node.js 版本需 ≥ 14.8.0（支持顶层 await 和稳定 ESM），且推荐使用 --loader ts-node/esm（若用 TypeScript）或配置 "type": "module"；
- describe 的第二个参数接受函数，Mocha 会将其作为作用域执行 —— 这与 CommonJS 中 require() 的行为语义一致，只是语法更规范。
? 扩展建议：
对于大量测试文件，可结合 glob 或 fs.promises.readdir 实现自动化加载（仍需在顶层完成）：
// test/all.mjs
import { readdir } from 'fs/promises';
import { join } from 'path';
const testDir = new URL('./specs/', import.meta.url);
const files = await readdir(testDir);
for (const file of files) {
if (file.endsWith('.spec.js')) {
const suite = await import(join(testDir, file));
describe(file.replace(/\.spec\.js$/, ''), suite.default);
}
}
此方式兼顾可维护性与 ESM 规范，是当前 Mocha + ESM 生态下的推荐实践。
