Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Advance time by hand

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.

Node.js Testing a debounce and a timeout without waiting

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

NODE
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'] leaves Date real. Passing 'Date' makes Date.now() and new Date() return the fake clock.
  • The fake clock jumps. During one tick(500), a callback that reads Date.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.
  • setImmediate runs on the first tick(), regardless of the amount of time you advance.
  • Cancel works. clearTimeout() and clearInterval() remove fake timers as usual.
  • Promises are not timers. If a timer callback resolves a promise, await that promise after tick() to let its continuation run.
  • Promise-based sleeps are not faked. In the Node.js 24 build used for these examples, await setTimeout(ms) from node:timers/promises kept waiting in real time even with 'setTimeout' enabled. Fake timers control the global setTimeout, setInterval and setImmediate, 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, forgetting reset() leaks fake timers into later tests. Using t.mock.timers avoids 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.