The native timer functions (i.e.,
clearInterval) are less than ideal for a testing environment since they depend on real time to elapse. Jest can swap out timers with functions that allow you to control the passage of time. Great Scott!
Here we enable fake timers by calling
jest.useFakeTimers(). This mocks out
setTimeout and other timer functions with mock functions. Timers can be restored to their normal behavior with
While you can call
jest.useRealTimers() from anywhere (top level, inside an
it block, etc.), it is a global operation and will affect other tests within the same file. Additionally, you need to call
jest.useFakeTimers() to reset internal counters before each test. If you plan to not use fake timers in all your tests, you will want to clean up manually, as otherwise the faked timers will leak across tests:
Another test we might want to write for this module is one that asserts that the callback is called after 1 second. To do this, we're going to use Jest's timer control APIs to fast-forward time right in the middle of the test:
There are also scenarios where you might have a recursive timer -- that is a timer that sets a new timer in its own callback. For these, running all the timers would be an endless loop… so something like
jest.runAllTimers() is not desirable. For these cases you might use
Another possibility is use
jest.advanceTimersByTime(msToRun). When this API is called, all timers are advanced by
msToRun milliseconds. All pending "macro-tasks" that have been queued via setTimeout() or setInterval(), and would be executed during this time frame, will be executed. Additionally, if those macro-tasks schedule new macro-tasks that would be executed within the same time frame, those will be executed until there are no more macro-tasks remaining in the queue that should be run within msToRun milliseconds.
Lastly, it may occasionally be useful in some tests to be able to clear all of the pending timers. For this, we have
The code for this example is available at examples/timer.