Merge branch 'main' into feat/fix-layout-shift

Author: denisx

.all-contributorsrc

@@ -2646,6 +2646,24 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "domnantas",
+      "name": "Domantas Petrauskas",
+      "avatar_url": "https://avatars.githubusercontent.com/u/51953549?v=4",
+      "profile": "https://domnantas.lt",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Efim-Kapliy",
+      "name": "Efim",
+      "avatar_url": "https://avatars.githubusercontent.com/u/126895483?v=4",
+      "profile": "https://portfolio.edkt.ru",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -506,10 +506,12 @@ Thanks goes to these wonderful people
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/smk267"><img src="https://avatars.githubusercontent.com/u/88115182?v=4?s=100" width="100px;" alt="smk267"/><br /><sub><b>smk267</b></sub></a><br /><a href="#infra-smk267" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/vadimshvetsov"><img src="https://avatars.githubusercontent.com/u/16336572?v=4?s=100" width="100px;" alt="Vadim Shvetsov"/><br /><sub><b>Vadim Shvetsov</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=vadimshvetsov" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://www.dylangordon.co.nz/"><img src="https://avatars.githubusercontent.com/u/3656794?v=4?s=100" width="100px;" alt="Dylan Gordon"/><br /><sub><b>Dylan Gordon</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=agentdylan" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://michael.cousins.io"><img src="https://avatars.githubusercontent.com/u/2963448?v=4?s=100" width="100px;" alt="Michael Cousins"/><br /><sub><b>Michael Cousins</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=mcous" title="Documentation">📖</a> <a href="https://github.com/testing-library/testing-library-docs/pulls?q=is%3Apr+reviewed-by%3Amcous" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://kettanaito.com"><img src="https://avatars.githubusercontent.com/u/14984911?v=4?s=100" width="100px;" alt="Artem Zakharchenko"/><br /><sub><b>Artem Zakharchenko</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=kettanaito" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/vadimshvetsov"><img src="https://avatars.githubusercontent.com/u/16336572?v=4?s=100" width="100px;" alt="Vadim Shvetsov"/><br /><sub><b>Vadim Shvetsov</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=vadimshvetsov" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://domnantas.lt"><img src="https://avatars.githubusercontent.com/u/51953549?v=4?s=100" width="100px;" alt="Domantas Petrauskas"/><br /><sub><b>Domantas Petrauskas</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=domnantas" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://portfolio.edkt.ru"><img src="https://avatars.githubusercontent.com/u/126895483?v=4?s=100" width="100px;" alt="Efim"/><br /><sub><b>Efim</b></sub></a><br /><a href="https://github.com/testing-library/testing-library-docs/commits?author=Efim-Kapliy" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>

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.
+
+:::

docs/react-testing-library/example-intro.mdx

@@ -66,10 +66,12 @@ test('loads and displays greeting', async () => {
 See the following sections for a detailed breakdown of the test
 
 :::note 
+
 We recommend using the
 [Mock Service Worker (MSW)](https://github.com/mswjs/msw) library to
 declaratively mock API communication in your tests instead of stubbing
 `window.fetch`, or relying on third-party adapters.
+
 :::
 
 ```jsx title="__tests__/fetch.test.jsx"

docs/react-testing-library/setup.mdx

@@ -31,10 +31,10 @@ make your test util file accessible without using relative paths.
 The example below sets up data providers using the [`wrapper`](api.mdx#wrapper)
 option to `render`.
 
-  <Tabs groupId="test-utils" defaultValue="jsx" values={[ {label: 'JavaScript',
-  value: 'jsx'}, {label: 'TypeScript', value: 'tsx'}, ]}>
+  <Tabs groupId="test-utils" defaultValue="js" values={[ {label: 'JavaScript',
+  value: 'js'}, {label: 'TypeScript', value: 'ts'}, ]}>
 
-  <TabItem value="jsx">
+  <TabItem value="js">
 
 ```diff title="my-component.test.jsx"
 - import { render, fireEvent } from '@testing-library/react';
@@ -70,7 +70,7 @@ export {customRender as render}
 
   </TabItem>
 
-  <TabItem value="tsx">
+  <TabItem value="ts">
 
 ```diff title="my-component.test.tsx"
 - import { render, fireEvent } from '@testing-library/react';
@@ -250,10 +250,10 @@ passing a [`queries`](api.mdx#render-options) option.
 If you want to add custom queries globally, you can do this by defining your
 customized `render`, `screen` and `within` methods:
 
-  <Tabs groupId="test-utils" defaultValue="jsx" values={[ {label: 'JavaScript',
-  value: 'jsx'}, {label: 'TypeScript', value: 'tsx'}, ]}>
+  <Tabs groupId="test-utils" defaultValue="js" values={[ {label: 'JavaScript',
+  value: 'js'}, {label: 'TypeScript', value: 'ts'}, ]}>
 
-  <TabItem value="jsx">
+  <TabItem value="js">
 
 ```js title="test-utils.js"
 import {render, queries, within} from '@testing-library/react'
@@ -278,7 +278,7 @@ export {customScreen as screen, customWithin as within, customRender as render}
 
   </TabItem>
 
-  <TabItem value="tsx">
+  <TabItem value="ts">
 
 ```ts title="test-utils.ts"
 import {render, queries, within, RenderOptions} from '@testing-library/react'

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> | void