Node.js Reference ยท util, assert and the Test Runner
Node.js mock.timers (fake timers in node:test)
Reference for mock.timers in node:test: enable fake setTimeout, setInterval, setImmediate and Date, advance time with tick() and runAll(), and reset afterwards.
mock.timers replaces Node.js timer functions with fakes that you control by hand. Instead of waiting 30 seconds for a setTimeout, you call mock.timers.tick(30_000) and the callback runs immediately. The fake clock can also stand in for Date, so code that reads the current time becomes deterministic.
Tests with real timers are slow and flaky. With fake timers a retry delay, a debounce, an interval or an expiry check runs in microseconds and gives the same result every time.
import { mock } from 'node:test'; mock.timers.enable({ apis: ['setTimeout'] }); setTimeout(() => console.log('fired'), 5000); mock.timers.tick(5000); // prints "fired" immediately mock.timers.reset();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
mock.timers.enable([options]) mock.timers.tick([milliseconds]) mock.timers.runAll() mock.timers.setTime(milliseconds) mock.timers.reset() t.mock.timers // same API, reset automatically when the test ends
| Method | Description |
|---|---|
enable({ apis, now }) |
Install fakes. apis is an array chosen from 'setTimeout', 'setInterval', 'setImmediate' and 'Date' (newer releases also accept 'scheduler.wait'); the default is all of them. now is the starting time in milliseconds (or a Date), default 0. |
tick(ms) |
Advance the fake clock by ms (default 1) and run every callback that becomes due, in time order. |
runAll() |
Run all pending timers and move the clock to the time of the last one. |
setTime(ms) |
Set the fake clock to an absolute time without running timers that were scheduled before. |
reset() |
Remove the fakes, restore the real functions and discard pending fake timers. |
Returns: undefined. The object also supports using, so using timers = mock.timers resets automatically at the end of a block.
Errors: tick() before enable() throws ERR_INVALID_STATE; an unknown name in apis throws ERR_INVALID_ARG_VALUE.
Usage notes
- Enable only what you need. Passing
apis: ['setTimeout']leavesDatereal. Passing'Date'makesDate.now()andnew Date()return the fake clock. - The fake clock jumps. During one
tick(500), a callback that readsDate.now()sees the clock after the whole advance, not the moment its own timer was due. Use small ticks when the exact time matters. - Ties and nesting. Timers scheduled inside a callback are scheduled relative to the fake clock. A single
tick()fires nested timers whose time falls inside the advanced span, but a timer created at the end of one tick runs on a later tick. setImmediateruns on the firsttick(), regardless of the amount of time you advance.- Cancel works.
clearTimeout()andclearInterval()remove fake timers as usual. - Promises are not timers. If a timer callback resolves a promise,
awaitthat promise aftertick()to let its continuation run. - Promise-based sleeps are not faked. In the Node.js 24 build used for these examples,
await setTimeout(ms)fromnode:timers/promiseskept waiting in real time even with'setTimeout'enabled. Fake timers control the globalsetTimeout,setIntervalandsetImmediate, so write the code under test with the callback form, or inject the delay function so a test can pass its own. - Always reset. With the global
mock.timers, forgettingreset()leaks fake timers into later tests. Usingt.mock.timersavoids this because it is reset at the end of each test. - Not an event-loop simulator. I/O,
process.nextTick()and promise callbacks are not controlled by it.