本文详解如何使用 Jest 的定时器 Mock 功能（jest.useFakeTimers() 及配套 API）可靠、高效地测试含 setTimeout 的 DOM 操作逻辑，避免因事件循环、微任务延迟或调用时机不当导致的断言失败。
本文详解如何使用 jest 的定时器 mock 功能（`jest.usefaketimers()` 及配套 api）可靠、高效地测试含 `settimeout` 的 dom 操作逻辑，避免因事件循环、微任务延迟或调用时机不当导致的断言失败。
在前端单元测试中，直接依赖真实时间执行 setTimeout 会导致测试缓慢、不稳定且难以断言——尤其当逻辑涉及 DOM 状态变更（如 Bootstrap Alert 的关闭）时，更需精确控制异步时机。Jest 提供的 Timer Mocks 机制正是为此而生：它将原生定时器函数（setTimeout/setInterval 等）替换为可编程的模拟版本，使你能在同步上下文中“快进时间”，从而实现确定性、高性能的测试。
✅ 正确启用与使用 Fake Timers
首先，必须在测试作用域内显式启用假定时器，并确保被测脚本实际执行（而非仅导入）：
// script.test.js
jest.useFakeTimers();
// ? 必须 spy setTimeout 才能验证其调用行为（官方推荐）
jest.spyOn(global, 'setTimeout');
describe("Timer alerts and then closes after 3000", () => {
beforeAll(() => {
const fs = require("fs");
const fileContents = fs.readFileSync("templates/base.html", "utf-8");
document.open();
document.write(fileContents);
document.close();
});
test('closes the alert after 3 seconds', () => {
const element = document.getElementById("msg");
expect(element).not.toBeNull();
expect(document.querySelector('.alert')).toBeTruthy();
// ⚠️ 关键：require 并立即执行脚本（否则 setTimeout 不会被注册）
const script = require('../script');
script(); // ← 这行必不可少！
// 验证 setTimeout 是否按预期注册
expect(setTimeout).toHaveBeenCalledTimes(1);
expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 3000);
// ✅ 推进时间 3000ms，触发回调
jest.advanceTimersByTime(3000);
// 此时 bootstrap.Alert.close() 已执行，DOM 应已移除 .alert 元素
expect(document.querySelector('.alert')).toBeNull();
});
});
? 为什么 jest.runAllTimers() 在此处不适用？
runAllTimers() 会立即执行所有待处理定时器（包括可能嵌套或递归注册的），但本例中仅有一个明确的 3000ms 延迟，且需严格验证“3秒后关闭”这一时间语义。advanceTimersByTime(3000) 更精准，它模拟时间流逝并仅触发该时刻到期的回调，符合业务逻辑语义。
⚠️ 常见陷阱与规避建议
- 未执行脚本：require('../script') 仅加载模块，若脚本无默认导出或自执行逻辑，则 setTimeout 根本不会被调用。务必显式调用（如 script()）或确保脚本为 IIFE。
- 未校验定时器调用：缺少 expect(setTimeout).toHaveBeenCalledTimes(1) 等断言，无法确认被测逻辑是否真正注册了定时器，易掩盖逻辑缺陷。
- 混淆 runAllTimers 与 advanceTimersByTime：前者适合“尽快执行所有”，后者适合“精确推进到某时刻”。对单次延时场景，后者语义更清晰、可控性更强。
-
遗漏 afterAll 清理：若在 describe 块中全局启用 fake timers，应在 afterAll 中恢复真实定时器，防止污染其他测试：
afterAll(() => { jest.useRealTimers(); });
✅ 最佳实践总结
| 场景 | 推荐 API | 说明 |
|---|---|---|
| 单次固定延时（如本例） | jest.advanceTimersByTime(ms) | 精确模拟时间流逝，保证回调在指定毫秒后触发 |
| 多个定时器需全部立即执行 | jest.runAllTimers() | 适用于轮询、重试等复杂宏/微任务链 |
| 仅执行当前已到期的定时器（防递归） | jest.runOnlyPendingTimers() | 避免 runAllTimers 触发新定时器导致无限循环 |
通过合理组合 useFakeTimers、advanceTimersByTime 和显式调用验证，你不仅能稳定测试 setTimeout 行为，更能将原本耗时数秒的测试压缩至毫秒级，大幅提升 CI/CD 效率与开发者体验。
