docs: clarify fake timer usage with user-event #1391
Conversation
✅ Deploy Preview for testing-library ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
docs/guides-using-fake-timers.mdx
Outdated
| @@ -51,3 +51,22 @@ afterEach(() => { | |||
| jest.useRealTimers() | |||
| }) | |||
| ``` | |||
|
|
|||
| ## Using fake timers together with `user-event` | |||
There was a problem hiding this comment.
Thanks for the PR @domnantas !
I do think that we shouldn't mention anything about user-event on this page though.
The reason for this is that this a "core" page.
For this PR the changes on this page can be reverted, and
- "This has a side effect - when using fake timers in
your tests, all of the code inside your test uses fake timers." can be a note on this page - the caution can be moved to https://testing-library.com/docs/user-event/options#advancetimers
Or do you see this differently @MatanBobi ?
There was a problem hiding this comment.
I 100% agree with you @timdeschryver :)
There was a problem hiding this comment.
Should I remove
`user-event` internally uses `setTimeout` to delay subsequent actions. Using
fake timers in such tests will cause timeouts, since the `setTimeout` callbacks
do not get executed. In order to allow `user-event` to advance the fake timers,
it is necessary to set [`advanceTimers`](user-event/options.mdx#advancetimers)
option in `userEvent.setup()`:
```js
const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime})
```
section entirely, or move it somewhere else?
I understand "user-event" and "core" are separate scopes, but when tests break due to fake timers, the Using fake timers page in docs is the first thing I checked. Maybe there should at least a note in this page linking to the advanceTimers option?
:::note
Using fake timers together with `user-event` may cause test timeouts. See [`advanceTimers`](user-event/options.mdx#advancetimers) option for clarification.
:::
There was a problem hiding this comment.
I think it can be removed, or moved to the user-event docs at the advance timers option (but I think it already mentions it).
I like the note 👍, let's add it to the core page (and revert the other changes).
There was a problem hiding this comment.
Simplified and moved the explanation to user-event/options.mdx. Left a short note on guides-using-fake-timers
| your tests with fake ones. This should be used sporadically and not on a regular | ||
| basis since using it contains some overhead. | ||
|
|
||
| When using fake timers in your tests, all of the code inside your test uses fake | ||
| timers. |
There was a problem hiding this comment.
I still stand by removing the This should be used sporadically and not on a regular basis since using it contains some overhead sentence. Fake timers are nothing to be scared of when used correctly. And in some cases (let's say you're developing a calendar module) they need to be used in nearly all of your tests :)
|
@all-contributors please add @domnantas for docs |
|
I've put up a pull request to add @domnantas! 🎉 |
fixes #1180
The docs do not clarify how to use fake timers together with
user-event. Added a section with an example how to properly set it up.