Sinon fake timers 的 `clock.now` 属性：读取当前假时间戳的完整指南

测试开发工具【免费下载链接】sinonTest spies, stubs and mocks for JavaScript.项目地址https://gitcode.com/gh_mirrors/si/sinon点击查看免费下载clock.now是 Sinon fake timers 返回的 clock 对象上的核心只读属性它以毫秒为单位返回当前假时间时间戳。凡是通过sinon.useFakeTimers()安装的定时器、Date与TemporalAPI其时间来源都归结到这个属性上。读完本文你将掌握clock.now的初始值设置方式数字、Date对象或配置对象、它与tick()/setSystemTime()/reset()等时间推进方法之间的联动关系以及如何用源码与测试用例验证其行为。clock.now是什么根据 fake-timers 概念文档 的定义fake timers 是setTimeout及其同类函数的同步实现Sinon 可以用它们覆盖全局函数从而更轻松地测试依赖时间的代码。安装后返回的clock对象承担着拨动时间的职责而clock.now就是这把时钟的当前读数返回当前假时间戳单位是毫秒Unix epoch 毫秒值它是一个随时间推进方法tick、tickAsync、jump、runAll等不断更新的属性安装 fake timers 后new Date()、Date.now()以及Temporal.Now.instant()等读取的都是这份假时间其底层时间值正是clock.now。初始值从哪来useFakeTimers的now参数clock.now的初始值完全取决于调用sinon.useFakeTimers()时传入的参数。从 fake-timers 工具模块 的文档可知有三种形态而 src/sinon/util/fake-timers.js 的源码把三种形态的解析逻辑写得非常清晰export function useFakeTimers(dateOrConfig) { const hasArguments typeof dateOrConfig ! undefined; const argumentIsDateLike (typeof dateOrConfig number || dateOrConfig instanceof Date) arguments.length 1; const argumentIsObject dateOrConfig ! null typeof dateOrConfig object arguments.length 1; if (!hasArguments) { return createClock({ now: 0 }); // ① 无参数从 0 开始 } if (argumentIsDateLike) { return createClock({ now: dateOrConfig }); // ② number 或 Date直接作为 now } if (argumentIsObject) { const config extend.nonEnum({}, dateOrConfig); const globalCtx config.global; delete config.global; return createClock(config, globalCtx); // ③ 配置对象整体传入 } throw new TypeError(useFakeTimers expected epoch or config object. ...); }三种初始化方式对clock.now初始值的影响如下调用方式clock.now初始值sinon.useFakeTimers()0UNIX epoch即 1970-01-01T00:00:00Zsinon.useFakeTimers(1483228800000)1483228800000数字毫秒时间戳sinon.useFakeTimers(new Date(2020-01-01T00:00:00Z))传入Date对象时取其getTime()结果sinon.useFakeTimers({ now: 1483228800000, ... })配置对象中的now字段值其中配置对象形态对应 use-fake-timers 文档中的配置表config.now的类型为Number/Date默认值为0语义是以指定的 unix epoch 安装 fake timers。也就是说即便以Date对象形式传入最终落到clock.now上的也是一个毫秒数值。时间推进后clock.now如何变化clock.now会随着一切时间推进方法同步更新这也是 fake timers 能模拟时间流逝的根本机制clock.tick(time)把时钟向前拨time毫秒并触发该时间范围内所有已排定的定时器回调之后clock.now增加timeclock.tickAsync(time)异步版会先打破事件循环让已排定的 promise 回调先执行再运行定时器clock.jump(time)向前跳跃时间每个回调至多触发一次适合模拟 JS 引擎如浏览器休眠后恢复的场景time与tick接受相同格式clock.runAll()/clock.runToLast()/clock.runToFrame()运行到某个边界后clock.now也会相应停在对应的时间点clock.reset()把时钟重置回初始的now值并清空所有挂起的定时器。值得注意tick接受的time参数除了毫秒数字还支持人类可读字符串如08表示 8 秒、01:00表示 1 分钟、02:34:10表示 2 小时 34 分 10 秒以及Temporal.Duration对象例如clock.tick(Temporal.Duration.from({ hours: 1, minutes: 30 }));无论以哪种形式推进最终clock.now的增量都以毫秒计算。与setSystemTime()的关键区别clock.setSystemTime([now])允许把系统时间直接改为给定的now数字或Date但不触发任何定时器。这与tick()的推进语义有本质区别tick(500)时间自然流过 500ms会触发这 500ms 内到期的所有定时器clock.now累加 500setSystemTime(...)时间发生瞬移直接改写clock.now已排定的定时器不受影响、不会提前触发。因此当测试需要修改当前时刻但不影响定时器调度例如模拟跨日、跨月、闰年场景时应使用setSystemTime需要让定时器按计划到期时应使用tick。与Date、Temporal的联动安装 fake timers 后Date构造函数与TemporalAPI 都会读取clock.now作为时间源这意味着const clock sinon.useFakeTimers({ now: 1000 }); new Date().getTime(); // 1000与 clock.now 一致 Date.now(); // 1000 Temporal.Now.instant().epochMilliseconds; // 1000 clock.tick(500); new Date().getTime(); // 1500这也是为什么 fake timers 能同时控制setTimeout、Date与Temporal它们共享同一份由clock.now表示的时间基准。源码层面的实现佐证在 src/sinon/util/fake-timers.js 中clock 的创建与安装委托给了sinonjs/fake-timers包Sinon 底层复用的正是这个独立包function createClock(config, globalCtx) { let FakeTimersCtx FakeTimers; if (globalCtx ! null typeof globalCtx object) { FakeTimersCtx FakeTimers.withGlobal(globalCtx); } const clock FakeTimersCtx.install(config); clock.restore clock.uninstall; return clock; }由此可以推断clock.now的实际实现位于sinonjs/fake-timers的 clock 内部install(config)时读取config.now无则默认 0之后由 tick 等推进逻辑维护返回值被显式挂上了clock.restore clock.uninstall因此测试结束用clock.restore()即可把被覆盖的全局函数还原若传入配置对象可通过global/target指定安装目标对象如 JSDOM 的 window此时clock.now仍是同一份时间基准只是作用域不同。测试用例如何验证clock.now仓库中的 now.test.js 是clock.now行为的最直接证据覆盖了两个核心场景// 场景一数字初始化 tick 推进 const clock sinon.useFakeTimers({ now: 1000 }); t.equal(clock.now, 1000, clock.now should be initial timestamp); clock.tick(500); t.equal(clock.now, 1500, clock.now should advance after tick); // 场景二Date 对象初始化 const startDate new Date(2020-01-01T00:00:00Z); const clock2 sinon.useFakeTimers(startDate); t.equal(clock2.now, startDate.getTime(), clock.now should match Date.getTime());这两个断言分别印证了上文的两点结论clock.now初始值等于now参数以Date对象初始化时取getTime()结果。此外tick 的测试、setSystemTime 的测试 与 reset 的测试 也都在各自场景中间接使用或断言了clock.now的取值可作为查阅联动行为的参考。实践建议与注意事项clock.now是只读读数不要在测试里直接给它赋值来改时间应使用tick()推进并触发定时器或setSystemTime()瞬移不触发定时器善用 Date 对象初始化以真实日历日期如new Date(2020-01-01T00:00:00Z)初始化比裸数字可读性更高且二者等价务必restore()useFakeTimers会覆盖全局setTimeout、Date、Temporal等Node.js 下还包括timers/timers/promises模块测试结束后应调用clock.restore()还原避免污染其他用例结合toFake/toNotFake收敛作用域并非所有测试都需要接管全部定时器可用配置对象精确指定要 fake 的函数如{ toFake: [setTimeout] }减少对全局的干扰注意shouldAdvanceTime模式开启后 fake time 会依据真实系统时间差自动增量推进默认每 20ms 检查一次此时clock.now会悄悄增长适合不确定何时调用tick()的场景但断言时需留意时间可能已前进。综合来看clock.now是理解 Sinon fake timers 时间模型的钥匙初始值由useFakeTimers的now参数决定随后被 tick 一族方法推进、被setSystemTime瞬移、被reset还原并始终作为Date/Temporal与各定时器 API 的统一时间源。赞分享测试开发工具【免费下载链接】sinonTest spies, stubs and mocks for JavaScript.项目地址https://gitcode.com/gh_mirrors/si/sinon点击查看免费下载相关推荐Sinon.js 假时间器Fake Timers使用指南Sinon.js 假时间器Fake Timers使用指南 项目介绍 Sinon.js 的 Fake Timers 是一个强大的JavaScript库它模拟开发工具Sinon fake timers 进阶clock.runToLast() / runToLastAsync() 完整实战指南Sinon fake timers 进阶 clock.runToLast / runToLastAsync 完整实战指南 本篇技术指南聚焦 Sinon.JS测试开发工具Sinon fake timers 中的 clock.countTimers()精准监控待处理定时器Sinon fake timers 中的 clock.countTimers 精准监控待处理定时器 clock.countTimers 是 Sinon.JS测试开发工具上一篇免费音频编辑神器Audacity从零开始制作专业级播客与音乐下一篇Hydrogen v2 Remix 模板的 Vercel 零配置部署指南Shopify 无头电商实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考