diff --git a/docs/guides-using-fake-timers.mdx b/docs/guides-using-fake-timers.mdx index 68bee9c5d..bc7ab201e 100644 --- a/docs/guides-using-fake-timers.mdx +++ b/docs/guides-using-fake-timers.mdx @@ -10,11 +10,8 @@ flaky. To solve these problems, or if you need to rely on specific timestamps in your code, most testing frameworks offer the option to replace the real timers in -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. +your tests with fake ones. This has a side effect - when using fake timers in +your tests, _all_ of the code inside your test uses fake timers. The common pattern to setup fake timers is usually within the `beforeEach`, for example: @@ -26,12 +23,10 @@ beforeEach(() => { }) ``` -When using fake timers, you need to remember to restore the timers after your -test runs. - -The main reason to do that is to prevent 3rd party libraries running after your -test finishes (e.g cleanup functions), from being coupled to your fake timers -and use real timers instead. +Since fake timers are mocking native timer functions, it is necessary to restore +the timers after your test runs, just like regular mocks. This prevents fake +timers leaking into other test cases and cleanup functions, where real timers +are expected. For that you usually call `useRealTimers` in `afterEach`. @@ -51,3 +46,11 @@ afterEach(() => { jest.useRealTimers() }) ``` + +:::note + +Combining fake timers with `user-event` may cause test timeouts. Refer to +[`advanceTimers`](user-event/options.mdx#advancetimers) option to prevent this +issue. + +::: diff --git a/docs/user-event/options.mdx b/docs/user-event/options.mdx index 13ec10768..014912680 100644 --- a/docs/user-event/options.mdx +++ b/docs/user-event/options.mdx @@ -8,8 +8,21 @@ can be applied per [`setup()`](setup.mdx). ### advanceTimers -If you are using fake timers, you need to advance your timers when we internally -[delay](#delay) subsequent code. +`user-event` adds a [delay](#delay) between some subsequent inputs. When using +[fake timers](/guides-using-fake-timers.mdx) it is necessary to set this option +to your test runner's time advancement function. For example: + +```js +const user = userEvent.setup({advanceTimers: jest.advanceTimersByTime}) +``` + +:::caution + +You may find suggestions to set `delay: null` to prevent test timeouts when +using fake timers. That is not recommended, as it may cause unexpected +behaviour. Starting from v14.1, we suggest using `advanceTimers` option instead. + +::: ```ts (delay: number) => Promise | void