Jest测试随机超时排查：无代码变更仍报错的解决过程

问题复盘 #

• 无征兆触发Jest测试超时错误：Error: thrown: 'Exceeded timeout of <x> for a test.'，未修改任何测试相关代码
• 常规排查无效：执行--detectOpenHandles未发现异步资源泄漏，尝试--forceExit也无法终止超时
• IDE提示异常：IntelliJ中该测试的test函数参数提示错误，显示(object: DoneCallback, method)
• 极端测试仍失败：简化测试为expect(1).toBe(1)同步断言后依然超时，但重写test函数定义行后，参数提示恢复正常，测试直接通过

根因分析 #

这种情况本质是IDE类型缓存或Jest内部缓存异常，导致test/it函数被错误识别为「需要传入DoneCallback的异步测试签名」。即便测试是同步的，Jest也会一直等待done()回调触发，最终触发超时。

解决方法 #

1. 临时快速修复：直接删除并重新输入测试的test()/it()函数行，让IDE重新识别正确的函数签名，这是最直接的恢复方式
2. 清理IDE缓存：在IntelliJ中执行File -> Invalidate Caches...，选择「Invalidate and Restart」，清除错误的类型提示缓存
3. 清理Jest缓存：执行命令 jest --clearCache，避免Jest加载旧的测试配置或缓存文件
4. 校验依赖版本：确认@types/jest包版本与Jest主版本完全匹配，版本不兼容可能导致类型识别异常

内容的提问来源于stack exchange，提问作者James Hill