Skip to content

Commit

Permalink
docs: update Timer Mocks guide for modern timers
Browse files Browse the repository at this point in the history
  • Loading branch information
@sigveio
sigveio committed Aug 6, 2021
1 parent 588b74b commit 24ed2a4
Show file tree
Hide file tree
Showing 3 changed files with 333 additions and 226 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

- `[website]` Use a darker background color for Note style admonitions in dark mode
- `[website]` Add CSS for line highlighting in docusaurus code blocks
- `[docs]` Update Timer Mocks guide for Jest 27 to be in line with the new default `modern` fake timers.

### Performance

Expand Down
279 changes: 166 additions & 113 deletions docs/TimerMocks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,110 @@ id: timer-mocks
title: Timer Mocks
---

The native timer functions (i.e., `setTimeout`, `setInterval`, `clearTimeout`, `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!](https://www.youtube.com/watch?v=QZoJ2Pt27BY)
The native timer functions (i.e., `setTimeout()`, `setInterval()`,
`clearTimeout()`, `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!][back-to-the-future-reference]

```javascript
// timerGame.js
'use strict';
[back-to-the-future-reference]: https://www.youtube.com/watch?v=QZoJ2Pt27BY

function timerGame(callback) {
console.log('Ready....go!');
setTimeout(() => {
console.log("Time's up -- stop!");
callback && callback();
}, 1000);
:::note

The default timer implementation changed in Jest 27 and is now based on
[@sinonjs/fake-timers][fake-timers-github].

:::

[fake-timers-github]: https://github.com/sinonjs/fake-timers

## Enabling fake timers

```js title="/examples/timer/modern/timerTest.js"
function timerTest(callback) {
setTimeout(() => callback('Timer finished!'), 10000);
}
module.exports = timerTest;
```

```js title="/examples/timer/modern/__tests__/timerTest.spec.js"
test('should invoke callback after timer ends', () => {
const timerTest = require('../timerTest');
const callback = jest.fn();

// highlight-start
// Enable mocking of native timer functions
jest.useFakeTimers();
// highlight-end

// Add a 10 second timer to invoke a mocked callback function
timerTest(callback);

// The callback should not have been called yet
expect(callback).not.toHaveBeenCalled();

// highlight-start
// Fast-forward until all timers have been executed
jest.runAllTimers();
// highlight-end

module.exports = timerGame;
// Assert successfully without having to wait for the 10 second delay
expect(callback).toBeCalledWith('Timer finished!');
});
```

```javascript
// __tests__/timerGame-test.js
'use strict';
Here we call `jest.useFakeTimers()` to replace `setTimeout()` and other native
timer functions with mock functions. And since we use `jest.runAllTimers()` to
fast forward in time, the callback has a chance to run before the test
completes.

## You are in the driver's seat

Fake timers will not automatically increment with the system clock. When they
are activated, time is essentially frozen until you say otherwise (or until
Jest times out).

In the previous example, we use `jest.runAllTimers()` to fast forward and run
all tasks queued by the mocked timer functions. Without telling Jest to advance
time like this, our callback would never be invoked.

You can also have more fine-grained control with for example
`jest.advanceTimersByTime()` or `jest.advanceTimersToNextTimer()`. See the
[API documentation](/docs/jest-object#mock-timers) for more information.

jest.useFakeTimers();
## Faking timers is a global operation

test('waits 1 second before ending the game', () => {
const timerGame = require('../timerGame');
timerGame();
Calling `jest.useRealTimers()` will turn on fake timers for all tests within
the same file, until normal timers are restored with `jest.useRealTimers()`.

The fake timers also have a global state that only resets each time you call
`jest.useFakeTimers()`.

So while `jest.useFakeTimers()` and `jest.useRealTimers()` can be called from
anywhere (top-level, inside a `test` block, etc.), you need to be careful
in order to avoid unexpected behavior.

```js
test('do something with fake timers', () => {
jest.useFakeTimers();
// ...
});

expect(setTimeout).toHaveBeenCalledTimes(1);
expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 1000);
test('do something with real timers (?)', () => {
// This would still use fake timers
});
```

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 `jest.useRealTimers()`.
In this example, since we never call `jest.useRealTimers()`, both tests
would end up using fake timers when run synchronously. And the state
(time/internal counters) of the fake timers would leak across since we did not
reset it.

While you can call `jest.useFakeTimers()` or `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:
A better approach could be:

```javascript
```js
afterEach(() => {
// Reset to real timers after each test
jest.useRealTimers();
});

Expand All @@ -49,130 +115,117 @@ test('do something with fake timers', () => {
// ...
});

test('do something else with fake timers', () => {
jest.useFakeTimers();
// ...
});

test('do something with real timers', () => {
// ...
});
```

## Run All Timers

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:

```javascript
test('calls the callback after 1 second', () => {
const timerGame = require('../timerGame');
const callback = jest.fn();

timerGame(callback);
Here we use an `afterEach` to call `jest.useRealTimers()` after every single
test.

// At this point in time, the callback should not have been called yet
expect(callback).not.toBeCalled();
This pattern can help keep behavior predictable as your test file
grows.

// Fast-forward until all timers have been executed
jest.runAllTimers();
- It will establish a clear baseline ->
"timers are real unless otherwise is set".
- The state of the fake timers is always reset between tests, since all tests
wanting to use them have to call `jest.useFakeTimers()` first.

// Now our callback should have been called!
expect(callback).toBeCalled();
expect(callback).toHaveBeenCalledTimes(1);
});
```
## Handling recursive timers

## Run Pending Timers
Scenarios exist where you might have a recursive timer -- for example a function
that sets a timer to call the same function again.

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 `jest.runOnlyPendingTimers()`:
If you use `jest.runAllTimers()` to advance time, it will execute all pending
tasks. If those tasks themselves schedule new tasks, those will be continually
exhausted until there are no more tasks remaining in the queue. So with a
recursive timer, you could end up with an infinite loop.

```javascript
// infiniteTimerGame.js
'use strict';
To solve this, Jest ships with an alternative called
`jest.runOnlyPendingTimers()`. This will run only the tasks queued by
`setTimeout()` or `setInterval()` up until that point.

function infiniteTimerGame(callback) {
console.log('Ready....go!');
```js title="/examples/timer/modern/infiniteTimerTest.js"
function infiniteTimerTest(callback) {
// Schedule the infiniteTimer() to start in 10 seconds
setTimeout(() => infiniteTimer(callback), 10000);
}

function infiniteTimer(callback) {
callback('infiniteTimer: start');
setTimeout(() => {
console.log("Time's up! 10 seconds before the next game starts...");
callback && callback();

// Schedule the next game in 10 seconds
setTimeout(() => {
infiniteTimerGame(callback);
}, 10000);
}, 1000);
callback('infiniteTimer: setTimeout');
// Invoke itself to immediately schedule another timer in a recursive loop
infiniteTimer(callback);
}, 10000);
}

module.exports = infiniteTimerGame;
module.exports = infiniteTimerTest;
```

```javascript
// __tests__/infiniteTimerGame-test.js
'use strict';

jest.useFakeTimers();

describe('infiniteTimerGame', () => {
test('schedules a 10-second timer after 1 second', () => {
const infiniteTimerGame = require('../infiniteTimerGame');
const callback = jest.fn();
```js title="/examples/timer/modern/__tests__/infiniteTimerTest.spec.js"
test('should not start recursive timer loop', () => {
const infiniteTimerTest = require('../infiniteTimerTest');
const callback = jest.fn();

infiniteTimerGame(callback);
jest.useFakeTimers();

// At this point in time, there should have been a single call to
// setTimeout to schedule the end of the game in 1 second.
expect(setTimeout).toHaveBeenCalledTimes(1);
expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 1000);
infiniteTimerTest(callback);

// Fast forward and exhaust only currently pending timers
// (but not any new timers that get created during that process)
jest.runOnlyPendingTimers();
// At this point only the timer in infiniteTimerTest() is scheduled,
// and time is frozen. So infiniteTimer() or the callback passed to it
// should not have been invoked.
expect(callback).not.toHaveBeenCalled();

// At this point, our 1-second timer should have fired it's callback
expect(callback).toBeCalled();
// highlight-start
jest.runOnlyPendingTimers();
// highlight-end

// And it should have created a new timer to start the game over in
// 10 seconds
expect(setTimeout).toHaveBeenCalledTimes(2);
expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 10000);
});
// Now the callback should have been invoked only once, at the beginning of
// infiniteTimer(). The setTimeout() within should have been ignored.
expect(callback).toHaveBeenCalledTimes(1);
expect(callback).toHaveBeenCalledWith('infiniteTimer: start');
});
```

## Advance Timers by Time
Thanks to using `jest.runOnlyPendingTimers()`, the test finishes successfully.

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.
If you replace it with `jest.runAllTimers()`, you will see that Jest throws an error:

```javascript
// timerGame.js
'use strict';
```error
Aborting after running 100000 timers, assuming an infinite loop!
```

function timerGame(callback) {
console.log('Ready....go!');
setTimeout(() => {
console.log("Time's up -- stop!");
callback && callback();
}, 1000);
}
Yikes... that's a lot of timers!

module.exports = timerGame;
```
## More code examples

```javascript
it('calls the callback after 1 second via advanceTimersByTime', () => {
const timerGame = require('../timerGame');
const callback = jest.fn();
TODO: Info about / link to more code examples here.

timerGame(callback);
## Frequently Asked Questions

// At this point in time, the callback should not have been called yet
expect(callback).not.toBeCalled();
### Timer functions are no longer a mock or spy function. How can I assert against them?

// Fast-forward until all timers have been executed
jest.advanceTimersByTime(1000);
In the legacy fake timers, prior to Jest 27, native timer functions were
replaced by Jest mock functions. After moving to a new implementation based on
an [external library][fake-timers-github], this is no longer a feature. So the
short answer is that you can't... at least not directly.

// Now our callback should have been called!
expect(callback).toBeCalled();
expect(callback).toHaveBeenCalledTimes(1);
});
```
The specific timer function used should be considered an implementation detail,
and it would generally be more robust to test against what you expect to happen
when a task runs.

Lastly, it may occasionally be useful in some tests to be able to clear all of the pending timers. For this, we have `jest.clearAllTimers()`.
Looking back at the first code example on this page, you will see that we
assert if the mocked callback function is called with the parameter we expect.
This decouples us from the details of what happens inside `timerTest()`. At
some point in the future, we can safely replace `setTimeout()` with another
timer without invalidating the test.

The code for this example is available at [examples/timer](https://github.com/facebook/jest/tree/master/examples/timer).
If you need to verify that callbacks are scheduled with a particular time or
interval, consider using `jest.advanceTimersByTime()` and make assertions based
on what you expect at different points in time.

0 comments on commit 24ed2a4

Please sign in to comment.