JavaScript单元测试中Promise超时断言需用Promise.race包装待测Promise与超时Promise，通过withTimeout辅助函数实现；Jest中推荐await expect(withTimeout(p, ms)).resolves/rejects断言，避免jest.setTimeout等误用。
在 JavaScript 单元测试中，对 Promise 的超时断言（即“这个异步操作必须在 X 毫秒内完成，否则失败”）不能靠 expect(promise).rejects.toThrow(...) 这类同步断言直接实现，因为 Promise 本身不暴露“是否超时”的状态。关键思路是：**用 Promise.race 包裹待测 Promise 和一个会在指定时间后 reject 的超时 Promise，再对 race 结果做断言。**
用 Promise.race 构建超时包装器
这是最通用、不依赖测试框架的方法。核心是手动创建一个“倒计时失败”的 Promise：
- 定义一个辅助函数
withTimeout(promise, ms, message = 'Operation timed out') - 内部使用
Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms))]) - 返回 race 后的 Promise —— 谁先 settle 就算谁赢
这样，如果原 Promise 在 ms 内没完成，超时 Promise 就会 reject，测试就能捕获到错误。
Jest 中推荐写法（支持 async/await）
Jest 原生支持 async 测试函数，配合 withTimeout 可写出清晰断言：
立即学习“Java免费学习笔记（深入）”；
test('fetchData should resolve within 100ms', async () => {
await expect(withTimeout(fetchData(), 100)).resolves.toBe('success');
});
test('slowOperation should reject due to timeout', async () => {
await expect(withTimeout(slowOperation(), 50)).rejects.toThrow('Operation timed out');
});
注意：不要写成 expect( withTimeout(...) ).resolves...，因为 expect().resolves 本身会等待 Promise，而 withTimeout 返回的就是可 await 的 Promise，直接 await 更直观可控。
避免常见陷阱
-
别用
jest.setTimeout替代业务超时：它只控制整个 test 的最大运行时间，不等于“验证逻辑在 Nms 内完成” -
慎用
done()回调 +setTimeout：容易因忘记调用done()或重复调用导致测试挂起或误报 -
超时时间要合理：CI 环境可能比本地慢，建议设为预期耗时的 2–3 倍，并考虑使用
jest.retryTimes应对偶发延迟 -
确保被测 Promise 真正异步：若 Promise 是同步 resolve/reject（如
Promise.resolve()），race 会立刻返回，超时不生效 —— 这说明你其实不需要超时校验
补充：Jest 也有现成工具（可选）
Jest v29+ 提供了 expect(...).toRejectAfter(ms) 和 .toResolveAfter(ms)（需启用 jest.enableAutomock()？不，实际是实验性 API，尚未稳定）。目前更稳妥的做法仍是手写 withTimeout，简洁、跨框架、语义明确。
