Skip to content

Commit b2be4bb

Browse files
authored
docs: clarify fake timer usage with user-event (#1391)
Closes #1180
1 parent 9739ce9 commit b2be4bb

File tree

2 files changed

+29
-13
lines changed

2 files changed

+29
-13
lines changed

docs/guides-using-fake-timers.mdx

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,8 @@ flaky.
1010

1111
To solve these problems, or if you need to rely on specific timestamps in your
1212
code, most testing frameworks offer the option to replace the real timers in
13-
your tests with fake ones. This should be used sporadically and not on a regular
14-
basis since using it contains some overhead.
15-
16-
When using fake timers in your tests, all of the code inside your test uses fake
17-
timers.
13+
your tests with fake ones. This has a side effect - when using fake timers in
14+
your tests, _all_ of the code inside your test uses fake timers.
1815

1916
The common pattern to setup fake timers is usually within the `beforeEach`, for
2017
example:
@@ -26,12 +23,10 @@ beforeEach(() => {
2623
})
2724
```
2825

29-
When using fake timers, you need to remember to restore the timers after your
30-
test runs.
31-
32-
The main reason to do that is to prevent 3rd party libraries running after your
33-
test finishes (e.g cleanup functions), from being coupled to your fake timers
34-
and use real timers instead.
26+
Since fake timers are mocking native timer functions, it is necessary to restore
27+
the timers after your test runs, just like regular mocks. This prevents fake
28+
timers leaking into other test cases and cleanup functions, where real timers
29+
are expected.
3530

3631
For that you usually call `useRealTimers` in `afterEach`.
3732

@@ -51,3 +46,11 @@ afterEach(() => {
5146
jest.useRealTimers()
5247
})
5348
```
49+
50+
:::note
51+
52+
Combining fake timers with `user-event` may cause test timeouts. Refer to
53+
[`advanceTimers`](user-event/options.mdx#advancetimers) option to prevent this
54+
issue.
55+
56+
:::

docs/user-event/options.mdx

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,21 @@ can be applied per [`setup()`](setup.mdx).
88

99
### advanceTimers
1010

11-
If you are using fake timers, you need to advance your timers when we internally
12-
[delay](#delay) subsequent code.
11+
`user-event` adds a [delay](#delay) between some subsequent inputs. When using
12+
[fake timers](/guides-using-fake-timers.mdx) it is necessary to set this option
13+
to your test runner's time advancement function. For example:
14+
15+
```js
16+
const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime})
17+
```
18+
19+
:::caution
20+
21+
You may find suggestions to set `delay: null` to prevent test timeouts when
22+
using fake timers. That is not recommended, as it may cause unexpected
23+
behaviour. Starting from v14.1, we suggest using `advanceTimers` option instead.
24+
25+
:::
1326

1427
```ts
1528
(delay: number) => Promise<void> | void

0 commit comments

Comments
 (0)