Skip to content

Commit edf5539

Browse files
committed
docs: move fake timer timeout explanation from core to user-event
1 parent 66e2dae commit edf5539

File tree

2 files changed

+17
-22
lines changed

2 files changed

+17
-22
lines changed

docs/guides-using-fake-timers.mdx

Lines changed: 4 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ code, most testing frameworks offer the option to replace the real timers in
1313
your tests with fake ones. This has a side effect - when using fake timers in
1414
your tests, _all_ of the code inside your test uses fake timers.
1515

16-
This becomes apparent when using [`user-event`](user-event/intro.mdx) to test
17-
user interactions. Internally, it uses `setTimeout` to
18-
[`delay`](user-event/options.mdx#delay) subsequent actions and allow
19-
asynchronous code to run between the inputs.
20-
2116
The common pattern to setup fake timers is usually within the `beforeEach`, for
2217
example:
2318

@@ -52,21 +47,10 @@ afterEach(() => {
5247
})
5348
```
5449

55-
## Using fake timers together with `user-event`
56-
57-
`user-event` internally uses `setTimeout` to delay subsequent actions. Using
58-
fake timers in such tests will cause timeouts, since the `setTimeout` callbacks
59-
do not get executed. In order to allow `user-event` to advance the fake timers,
60-
it is necessary to set [`advanceTimers`](user-event/options.mdx#advancetimers)
61-
option in `userEvent.setup()`:
62-
63-
```js
64-
const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime})
65-
```
66-
67-
:::caution
50+
:::note
6851

69-
You may find suggestions to set `delay: null` in `userEvent.setup()` in order to
70-
solve this issue. That is not recommended, as it may cause unexpected behaviour.
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.
7155

7256
:::

docs/user-event/options.mdx

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,19 @@ 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+
`jest.advanceTimersByTime`, `vi.advanceTimersByTime`, or `mock.timers.tick` for
15+
`node:test`.
16+
17+
:::caution
18+
19+
You may find suggestions to set `delay: null` to prevent test timeouts when
20+
using fake timers. That is not recommended, as it may cause unexpected
21+
behaviour. Starting from v14.1, we suggest using `advanceTimers` option instead.
22+
23+
:::
1324

1425
```ts
1526
(delay: number) => Promise<void> | void

0 commit comments

Comments
 (0)