@sinonjs/fake-timers

中文文档

15.4.0发布于 2026/05/06BSD-3-ClauseTypeScriptCommonJS近 30 天下载 3.1亿

假 JavaScript 计时器

文档目录41 节

自动完成、 IntelliSense 和 TypeScript 定义
安装
使用量
假扮本地计时器
API 参考
var clock = FakeTimers.createClock([now[, loopLimit]])
var clock = FakeTimers.install([config])
clock.setTickMode(mode)
var id = clock.setTimeout(callback, timeout)
clock.clearTimeout(id)
var id = clock.setInterval(callback, timeout)
clock.clearInterval(id)
var id = clock.setImmediate(callback)
clock.clearImmediate(id)
clock.requestAnimationFrame(callback)
clock.cancelAnimationFrame(id)
clock.requestIdleCallback(callback[, timeout])
clock.cancelIdleCallback(id)
clock.countTimers()
clock.hrtime(prevTime?)
clock.nextTick(callback)
clock.performance.now()
clock.tick(time) 编号 : await clock.tickAsync(time)
clock.next() 编号 : await clock.nextAsync()
clock.jump(time)
clock.reset()
clock.runAll() 编号 : await clock.runAllAsync()
clock.runMicrotasks()
clock.runToFrame()
clock.runToLast() 编号 : await clock.runToLastAsync()
clock.setSystemTime([now])
clock.uninstall()
Date
Performance
FakeTimers.withGlobal
承诺和假时间
正在测试
节点:
在浏览器中
许可证
捐款

`@sinonjs/fake-timers`

Java 脚本执行定时器 APIs(英语:APIs; setTimeout, (中文(简体) ), clearTimeout, (中文(简体) ), setImmediate, (中文(简体) ), clearImmediate, (中文(简体) ), setInterval, (中文(简体) ), clearInterval, (中文(简体) ), requestAnimationFrame, (中文(简体) ), cancelAnimationFrame, (中文(简体) ), requestIdleCallback, (中文(简体) ), 财务报告和审定财务报表 cancelIdleCallback,以及控制时间流的时钟实例。假时报还提供 Date 执行时间从时钟算起.

除浏览器环境外 @sinonjs/fake-timers 页:1 performance 时间的落实从时钟。在节点环境中,假时提供 nextTick 同步执行时钟 - 和 a process.hrtime 和时钟一起工作的人.

@sinonjs/fake-timers 可用于在自动测试和其他测试中模拟通过时间需要排程语义的情况,但实际上不想单单.

@sinonjs/fake-timers 属于西农. 联合来文和目标页:1 相同的运行时间。。。 .

自动完成、 IntelliSense 和 TypeScript 定义

@sinonjs/fake-timers 由JSDoc生成内置类型定义的船舶. 在支持IDE和TypeScript项目时提供自动完整和类型建议,而不需要外部 @types 软件包.

安装

@sinonjs/fake-timers 可以在节点和浏览器环境中使用. 安装和安装一样容易

npm install @sinonjs/fake-timers

如果你想使用的话 @sinonjs/fake-timers 您可以在浏览器中构建自己的捆绑或使用情况天盘。。。 .

使用量

用于 @sinonjs/fake-timers,创建新的时钟, 使用计时器安排其上的事件函数和通过时间 tick 方法.

// In the browser distribution, a global `FakeTimers` is already available
var FakeTimers = require("@sinonjs/fake-timers");
var clock = FakeTimers.createClock();

clock.setTimeout(function () {
    console.log(
        "The poblano is a mild chili pepper originating in the state of Puebla, Mexico.",
    );
}, 15);

// ...

clock.tick(15);

执行最后一行后, 一个有趣的事实波布拉诺将同步打印到屏幕。如果你想模拟同步行为,请看 async 函数变体( e) 语法 clock.tick(time) 对 await clock.tickAsync(time)) (中文(简体) ).

这个 next, (中文(简体) ), runAll, (中文(简体) ), runToFrame,以及 runToLast 提供推进时钟的方法。见 API 详情参考.

假扮本地计时器

使用时 @sinonjs/fake-timers 到测试定时器时,您很可能想要替换本地这样的计时器 setTimeout 实际为您安排回调时钟实例,不是浏览器的内部.

通话 install 没有论据可以实现这一点。你可以打电话 uninstall 后来恢复原样. 注意在节点JS中计时器财务报告和审定财务报表计时器/保证当使用全球范围.

// In the browser distribution, a global `FakeTimers` is already available
var FakeTimers = require("@sinonjs/fake-timers");

var clock = FakeTimers.install();
// Equivalent to
// var clock = FakeTimers.install(typeof global !== "undefined" ? global : window);

setTimeout(fn, 15); // Schedules with clock.setTimeout

clock.uninstall();
// setTimeout is restored to the native implementation

劫机计时器在另一个背景中传递给 install 方法.

var FakeTimers = require("@sinonjs/fake-timers");
var context = {
    setTimeout: setTimeout, // By default context.setTimeout uses the global setTimeout
};
var clock = FakeTimers.withGlobal(context).install();

context.setTimeout(fn, 15); // Schedules with clock.setTimeout

clock.uninstall();
// context.setTimeout is restored to the original implementation

通常您想要将定时器安装到全局对象上, 所以调用 install 没有争论.

模拟时间自动递增

假时器支持将假时器附加到任何更改中的可能性在真实的系统时间。这意味着没有必要 tick() 页:1 在你不知道的情况下的时钟何时调用 tick()。。。 .

请注意,这是使用最初的设置Immediate()实现的。 API 在一个特定的可配置间隔 config.advanceTimeDelta (默认:20ms). 意义时间会每20米递增一次,而不是实时.

一个例子是:

var FakeTimers = require("@sinonjs/fake-timers");
var clock = FakeTimers.install({
    shouldAdvanceTime: true,
    advanceTimeDelta: 40,
});

setTimeout(() => {
    console.log("this just timed out"); //executed after 40ms
}, 30);

setImmediate(() => {
    console.log("not so immediate"); //executed after 40ms
});

setTimeout(() => {
    console.log("this timed out after"); //executed after 80ms
    clock.uninstall();
}, 50);

除以上外,可以对被嘲笑的时间进行配置以更快地推进使用 clock.setTickMode({ mode: "nextAsync" });时钟提前到第一个预定的计时器,然后用一个循环点燃它。在每个计时器之间, 它也会打破事件循环允许任何预定的约定要执行的回调 在此之前 运行下一个.

API 参考

`var clock = FakeTimers.createClock([now[, loopLimit]])`

创建时钟。默认时代实值 0。。。 .

这个 now 参数可以是数字(以毫秒计),a Date 对象, a Temporal.Instant,或一个 Temporal.ZonedDateTime。。。 .

这个 loopLimit 参数设置调用时运行的最大定时器数 runAll() 假设之前我们有一个无限的回路并投出一个错误。默认是 1000。。。 .

`var clock = FakeTimers.install([config])`

使用指定的配置安装假时 0 (关于全球范围的问题). 注意在节点JS中计时器财务报告和审定财务报表计时器/保证当使用全球范围. 以下配置选项可供选择

参数	类型	默认	说明
`config.now`	数字/日期/时间。即时/即时. ZonedDate Time	0 个	用指定的 unix 时代安装假时
`config.toFake`	字符串 []	["设置时通","设置时通","设置时通","设置时通","设置时通","定时通"等] 加上,当本地有:"设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","设置时通","性能","请求AnimationFrame","queueMicrotask","celAnimationFrame","设置后通","请求IdleCallback","CancelIdleCallback","Intl","设置时通","设置时通"临时通"	带有明确函数名的阵列(或物体,如果是“性能”)来劫持。在未设定时,"假时"会自动伪造出所有方法,例如,,,, `FakeTimers.install({ toFake: ["setTimeout","nextTick"]})` 只会伪造 `setTimeout` 财务报告和审定财务报表 `nextTick`组合 `config.toNotFake`。。。 . `"Temporal"` 全部伪造 `Temporal.Now.*` 方法(要求有26+节点或有当地临时支持的环境).
`config.toNotFake`	字符串 []	[	带有明确函数名称的阵列,这些函数名称应保持原生。设定时,"假时空"会伪造其他支持的方法,例如,, `FakeTimers.install({ toNotFake: ["Date"] })` 伪造所有支持的方法,但 `Date`组合 `config.toFake`。。。 .
`config.loopLimit`	数目	1 000个	调用 runAll () 时运行的最大计时器数
`config.shouldAdvanceTime`	布尔	虚假	告诉"假时空"根据实时系统时间倒移自动进行增量模拟时间(例如,被模拟时间在实时系统时间中每改变20ms就会增加20ms)
`config.advanceTimeDelta`	数目	20国	仅在使用时 `shouldAdvanceTime: true`被嘲笑的时间 `advanceTimeDelta` 分钟每 `advanceTimeDelta` ms在实时系统时间变化.
`config.shouldClearNativeTimers`	布尔	虚假	告诉"假时"(fakeTimers)通过授权给各自的处理者来清除"本地"(即不是假)计时器. 如果在安装假时器之前存在计时器,这些不默认地被清除,导致潜在的出乎意料的行为.
`config.ignoreMissingTimers`	布尔	虚假	让"假时空"忽略在特定环境中可能不存在的缺失定时器

`clock.setTickMode(mode)`

允许配置时钟如何自动或手动推进时间.

推进计时器有三种不同的模式:

{mode: 'manual'}: 计时器在没有明确、手动呼叫勾选时不会前进 APIs (英语:clock.nextAsync, (中文(简体) ), clock.runAllAsync(见E/CN.4/Sub.2/2002/L.48等)。此模式相当于 false。。。 .
{mode: 'nextAsync'}:时钟会持续地打破事件循环,再运行下个计时器直到模式改变. 因此,测试可以独立于是否安装了假定时器的方式来书写. 测试总是可以被写成等待定时器解决,即使使用假定时器.
{mode: 'interval', delta?: <number>}: 这与指定相同 shouldAdvanceTime: true 带有 advanceTimeDelta如果三角洲是未指定, 将默认使用 20.

“ nextAsync” 模式不同于 interval 在两个关键方面:

允许在每次计时器执行间空出微任务队列, 没有安装假定时器的情况也是如此.
它的推进速度越快越好如果下一个计时器在排队时间是1000ms,它会立即推进1000ms 而间隔, 在测试中不需要手动推进时间 1000 / advanceTimeDelta 实时到达并执行计时器.

`var id = clock.setTimeout(callback, timeout)`

计划一次发射回调 timeout 毫秒已经过去了.

在节点.js setTimeout 返回计时器对象。但是假时空也一样联合国 ref() 财务报告和审定财务报表 unref() 方法没有效果.

在浏览器中返回计时器ID.

`clock.clearTimeout(id)`

清除给定的ID或定时器对象的定时器,只要它使用 setTimeout。。。 .

`var id = clock.setInterval(callback, timeout)`

安排每次发射的回调 timeout 毫秒已选中由来.

在节点.js setInterval 返回计时器对象。但是假时空也一样联合国 ref() 财务报告和审定财务报表 unref() 方法没有效果.

在浏览器中返回计时器ID.

`clock.clearInterval(id)`

清除给定的ID或定时器对象的定时器,只要它使用 setInterval。。。 .

`var id = clock.setImmediate(callback)`

计划一次发射回调 0 毫秒已经过去了说明你仍然需要打电话 clock.tick() 为召回开火。若为一时钟打来电话召回不会开火直到 1 毫秒已选中由来.

在节点.js setImmediate 返回计时器对象。假时辰也会这样, 但它 ref() 财务报告和审定财务报表 unref() 方法没有效果.

在浏览器中返回计时器ID.

`clock.clearImmediate(id)`

清除给定的ID或定时器对象的定时器,只要它使用 setImmediate。。。 .

`clock.requestAnimationFrame(callback)`

排出在下个动画框上发射的回调 16个虱子。返回 a id 用于取消回调。这是在两个浏览器和节点环境中都可以使用.

`clock.cancelAnimationFrame(id)`

取消由 ID 安排的调用.

`clock.requestIdleCallback(callback[, timeout])`

排出空闲期间被放出回调,以进行主事件回调圈的背景和低优先工作. 有超时选项的回调将在毫秒内发射。返回 a id 这可能是用于取消回调.

`clock.cancelIdleCallback(id)`

取消由 ID 安排的调用.

`clock.countTimers()`

返回等待计时器的数量。这可以用来断言测试完成时不漏出任何计时器.

`clock.hrtime(prevTime?)`

仅在Node.js, mimicks process.hrtime ()中可用.

`clock.nextTick(callback)`

只有Node.js, 模拟 process.nextTick 使测试流程完全同步.

`clock.performance.now()`

仅在浏览器环境中可用, mimicks performance.now ().

`clock.tick(time)` 编号 : `await clock.tickAsync(time)`

提前计时,必要时发射回调. time 可能为以可读字符串或 Temporal.Duration (要求节点26+或具有本地时间的环境) 支持)。有效的字符串格式为 "08" 8秒钟, "01:00" 一个分钟和 "02:34:10" 2小时34分10秒.

这个 tickAsync() 也可以打破事件循环,允许任何预定的约定要执行的回调 在此之前 运行计时器.

`clock.next()` 编号 : `await clock.nextAsync()`

将钟推进到第一个定时器的时刻,发射.

这个 nextAsync() 也可以打破事件循环,允许任何预定的约定要执行的回调 在此之前 运行计时器.

`clock.jump(time)`

通过及时跳跃推进时钟,最多一次发射回调. time 格式与 clock.tick。。。 .

这可以用来模拟JS引擎(如浏览器)被放入睡眠后恢复,跳出中间计时器.

`clock.reset()`

删除所有计时器和计时器而不发射,并设定 now 改为 config.now 提供给 FakeTimers.install 或改为 0 若为 config.now 没有提供. 用于重设时钟状态而无需 uninstall 财务报告和审定财务报表 install 这个.

`clock.runAll()` 编号 : `await clock.runAllAsync()`

运行所有待定的定时器,直到没有剩余时间为止。如果在执行时添加了新的计时器, 它们将会是运行也一样.

这使得在不担心使用计时器数量的情况下进行同步测试以完成比较容易,或者那些时间的拖延.

它运行最多 loopLimit 之后它假设有无限循环的计时器并扔出一个错误.

这个 runAllAsync() 也可以打破事件循环,允许任何预定的约定要执行的回调 在此之前 运行计时器.

`clock.runMicrotasks()`

这将运行所有预定的未完成的微任务 nextTick 但没有计时器,而且对图书馆大多有用在下方和运行时使用假时间 nextTick 没有计时器的项目.

`clock.runToFrame()`

将时钟提前到下一个帧, 发射所有预定的动画帧回调, 如果有的话,为这个框架以及沿途安排的任何其他计时器.

`clock.runToLast()` 编号 : `await clock.runToLastAsync()`

注意到运行时的最后一个预定定时器,并推进时钟到那个时间发射回调的必要.

如果在执行时添加了新的计时器, 则只能运行它们将会在这之前发生.

这在您想要运行一个测试到完成时有用, 但测试是递归的将引发的定时器 runAll 以触发无限循环警告.

这个 runToLastAsync() 也可以打破事件循环,允许任何预定的约定要执行的回调 在此之前 运行计时器.

`clock.setSystemTime([now])`

这模拟了一个用户在程序运行时更改系统时钟. 它影响当前时间,但本身并不导致如定时器起火; 他们将像他们本该做的一样射击,而不召唤 setSystem Time (). (中文). 这个 now 参数可以是数字(以毫秒计),a Date 对象, a Temporal.Instant,或一个 Temporal.ZonedDateTime。。。 .

`clock.uninstall()`

恢复原生定时器的原始方法或对象上的方法被传递到 FakeTimers.withGlobal

`Date`

执行 Date 对象,但使用时钟提供正确的时间.

`Performance`

执行 now 方法 Performance 对象,但使用时钟提供正确的时间。仅在支持性能的环境下可用对象(主要是浏览器).

`FakeTimers.withGlobal`

为了支持基于单独或沙盒环境创建时钟(如JSDOM),假时钟输出 a 采用单一参数的工厂方法 global,它检查找出什么可以嘲笑和什么特点支助。当使用全局函数引用此函数时,您将会以 timers, (中文(简体) ), createClock 财务报告和审定财务报表 install - 与常规假时器出口相同,只是根据全球的过去而不是全球的过去环境.

承诺和假时间

如果你像"蓝鸟"一样使用"承诺"图书馆,请注意,你要么打电话 clock.runMicrotasks() 或确保没有模拟 nextTick。。。 .

正在测试

假时人有一个综合测试套房. 如果你在考虑贡献错误修正或建议新特性,需要确保您没有损坏任何测试。您还需要加入任何新行为的测试 .

节点:

npm test

或者,如果你更喜欢动词输出:

$(npm bin)/mocha ./test/fake-timers-test.js

在浏览器中

模拟用于无头测试克罗姆.

npm test-headless

许可证

BSD 3- clause “ 新建” 或“ 修订” 许可证( 见 LICENSE 文件)

捐款

@sinonjs/fake-timers 使用 JSDoc 在 src/fake-timers-src.js 作为它公开类型的真理的来源. TypeScript 声明会从此文件中自动生成. 贡献变化时 :

更新联合来文说明 src/fake-timers-src.js 如果公共API改变.
运行 npm run types:build 重新生成在 types/。。。 .
保证 npm run types:smoke 仍然通过验证生成的类型.
tsgo 用作平行验证道,以确保与未来的TypeScript版本相兼容.

版本与发布记录

@sinonjs/fake-timers 共发布 50 个版本，首次发布于 2020/02/04；过去 12 个月发布了 11 个版本。

版本	发布日期	距今
`15.4.0`latest	2026/05/06	6 个月前
`15.3.2`	2026/04/12	6 个月前
`15.3.1`	2026/04/11	6 个月前
`15.3.0`	2026/04/02	7 个月前
`15.2.2`	2026/04/02	7 个月前
`15.2.2-alpha.0`alpha	2026/04/02	7 个月前

关于 @sinonjs/fake-timers 的常见问题

@sinonjs/fake-timers 是什么？

假 JavaScript 计时器

如何安装 @sinonjs/fake-timers？

在项目目录运行 npm install @sinonjs/fake-timers，或使用 pnpm add / yarn add / bun add。

@sinonjs/fake-timers 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@sinonjs/fake-timers 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@sinonjs/fake-timers 可以商用吗？

@sinonjs/fake-timers 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

@sinonjs/fake-timers 的下载量有多少？

根据 npm 官方下载统计，@sinonjs/fake-timers 在 2026/10/07 – 2026/11/05 这 30 天内被下载 305,489,856 次，日均约 10,182,995 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@sinonjs/fake-timers 还在维护吗？

最新版本 15.4.0 发布于 2026/05/06（6 个月前）；至今共发布 50 个版本，其中过去 12 个月发布了 11 个；首次发布于 2020/02/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @sinonjs/fake-timers

pnpmpnpm add @sinonjs/fake-timers
yarnyarn add @sinonjs/fake-timers
bunbun add @sinonjs/fake-timers

在你的项目目录中运行此命令。

近 30 天下载

305,489,856

约 3.1亿次日均 10,182,995 次

统计周期 2026/10/07 – 2026/11/05
数据来自 npm 官方下载统计，今天更新

最新版本15.4.0发布于 6 个月前

开源许可BSD-3-Clause宽松许可

包体积147 kB5 个文件 · 解压后

运行依赖1 个

模块格式CommonJS

TypeScript自带类型

发布版本50 个近 12 个月 11 个

首次发布2020/02/046 年前

元数据更新2026/05/06

每一个软件包背后，
都有分享与创造的人。

@sinonjs/fake-timers

@sinonjs/fake-timers

自动完成、 IntelliSense 和 TypeScript 定义

安装

使用量

假扮本地计时器

模拟时间自动递增

API 参考

var clock = FakeTimers.createClock([now[, loopLimit]])

var clock = FakeTimers.install([config])

clock.setTickMode(mode)

var id = clock.setTimeout(callback, timeout)

clock.clearTimeout(id)

var id = clock.setInterval(callback, timeout)

clock.clearInterval(id)

var id = clock.setImmediate(callback)

clock.clearImmediate(id)

clock.requestAnimationFrame(callback)

clock.cancelAnimationFrame(id)

clock.requestIdleCallback(callback[, timeout])

clock.cancelIdleCallback(id)

clock.countTimers()

clock.hrtime(prevTime?)

clock.nextTick(callback)

clock.performance.now()

clock.tick(time) 编号 : await clock.tickAsync(time)

clock.next() 编号 : await clock.nextAsync()

clock.jump(time)

clock.reset()

clock.runAll() 编号 : await clock.runAllAsync()

clock.runMicrotasks()

clock.runToFrame()

clock.runToLast() 编号 : await clock.runToLastAsync()

clock.setSystemTime([now])

clock.uninstall()

Date

Performance

FakeTimers.withGlobal

承诺和假时间

正在测试

节点:

在浏览器中

许可证

捐款

版本与发布记录

关于 @sinonjs/fake-timers 的常见问题

@sinonjs/fake-timers 是什么？

如何安装 @sinonjs/fake-timers？

@sinonjs/fake-timers 支持 TypeScript 吗？

@sinonjs/fake-timers 支持 ESM 还是 CommonJS？

@sinonjs/fake-timers 可以商用吗？

@sinonjs/fake-timers 的下载量有多少？

@sinonjs/fake-timers 还在维护吗？

`@sinonjs/fake-timers`

`var clock = FakeTimers.createClock([now[, loopLimit]])`

`var clock = FakeTimers.install([config])`

`clock.setTickMode(mode)`

`var id = clock.setTimeout(callback, timeout)`

`clock.clearTimeout(id)`

`var id = clock.setInterval(callback, timeout)`

`clock.clearInterval(id)`

`var id = clock.setImmediate(callback)`

`clock.clearImmediate(id)`

`clock.requestAnimationFrame(callback)`

`clock.cancelAnimationFrame(id)`

`clock.requestIdleCallback(callback[, timeout])`

`clock.cancelIdleCallback(id)`

`clock.countTimers()`

`clock.hrtime(prevTime?)`

`clock.nextTick(callback)`

`clock.performance.now()`

`clock.tick(time)` 编号 : `await clock.tickAsync(time)`

`clock.next()` 编号 : `await clock.nextAsync()`

`clock.jump(time)`

`clock.reset()`

`clock.runAll()` 编号 : `await clock.runAllAsync()`

`clock.runMicrotasks()`

`clock.runToFrame()`

`clock.runToLast()` 编号 : `await clock.runToLastAsync()`

`clock.setSystemTime([now])`

`clock.uninstall()`

`Date`

`Performance`

`FakeTimers.withGlobal`