Merge branch 'main' into all-contributors/add-vadimshvetsov

Author: MatanBobi

.all-contributorsrc

@@ -2610,10 +2610,39 @@
         "infra"
       ]
     },
+    {
+      "login": "agentdylan",
+      "name": "Dylan Gordon",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3656794?v=4",
+      "profile": "https://www.dylangordon.co.nz/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "mcous",
+      "name": "Michael Cousins",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2963448?v=4",
+      "profile": "https://michael.cousins.io",
+      "contributions": [
+        "doc",
+        "review"
+      ]
+    },
+    {
+      "login": "kettanaito",
+      "name": "Artem Zakharchenko",
+      "avatar_url": "https://avatars.githubusercontent.com/u/14984911?v=4",
+      "profile": "https://kettanaito.com",
+      "contributions": [
+        "doc"
+      ]
+    },
     {
       "login": "vadimshvetsov",
       "name": "Vadim Shvetsov",
       "avatar_url": "https://avatars.githubusercontent.com/u/16336572?v=4",
+      "profile": "https://github.com/vadimshvetsov",
       "contributions": [
         "doc"
       ]

README.md

@@ -506,7 +506,10 @@ 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://proling.ru"><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://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>
     </tr>
   </tbody>
 </table>

docs/angular-testing-library/api.mdx

@@ -150,6 +150,42 @@ await render(AppComponent, {
 })
 ```
 
+### `deferBlockBehavior`
+
+Set the defer blocks behavior.
+
+For more info see the
+[Angular docs](https://angular.io/api/core/testing/DeferBlockBehavior)
+
+**default** : `undefined` (uses the Angular default, which is
+`DeferBlockBehavior.Manual`)
+
+**example**:
+
+```typescript
+await render(AppComponent, {
+  deferBlockBehavior: DeferBlockBehavior.Playthrough,
+})
+```
+
+### `deferBlockStates`
+
+Set the initial state of a deferrable blocks in a component.
+
+For more info see the
+[Angular docs](https://angular.io/api/core/testing/DeferBlockState)
+
+**default** : `undefined` (uses the Angular default, which is
+`DeferBlockState.Placeholder`)
+
+**example**:
+
+```typescript
+await render(FixtureComponent, {
+  deferBlockStates: DeferBlockState.Loading,
+})
+```
+
 ### `componentProviders`
 
 A collection of providers needed to render the component via Dependency
@@ -395,20 +431,39 @@ properties that are not defined are cleared.
 
 ```typescript
 const {rerender} = await render(Counter, {
-  componentProperties: {count: 4, name: 'Sarah'},
+  componentInputs: {count: 4, name: 'Sarah'},
 })
 
 expect(screen.getByTestId('count-value').textContent).toBe('4')
 expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
 
-await rerender({componentProperties: {count: 7}})
+await rerender({componentInputs: {count: 7}})
 
-// count updated to 7
+// count is updated to 7
 expect(screen.getByTestId('count-value').textContent).toBe('7')
 // name is undefined because it's not provided in rerender
 expect(screen.getByTestId('name-value').textContent).toBeUndefined()
 ```
 
+Using `partialUpdate`, only the newly provided properties will be updated. Other
+input properties that aren't provided won't be cleared.
+
+```typescript
+const {rerender} = await render(Counter, {
+  componentInputs: {count: 4, name: 'Sarah'},
+})
+
+expect(screen.getByTestId('count-value').textContent).toBe('4')
+expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
+
+await rerender({componentInputs: {count: 7}, partialUpdate: true})
+
+// count is updated to 7
+expect(screen.getByTestId('count-value').textContent).toBe('7')
+// name is still rendered as "Sarah" because of the partial update
+expect(screen.getByTestId('name-value').textContent).toBe('Sarah')
+```
+
 ### `detectChanges`
 
 Trigger a change detection cycle for the component.
@@ -473,3 +528,22 @@ screen.getByRole('heading', {
 })
 queryByLabelText(/First name/i')
 ```
+
+### `renderDeferBlock`
+
+To test [Deferrable views](https://angular.dev/guide/defer#defer), you can make
+use of `renderDeferBlock`. `renderDeferBlock` will set the desired defer state
+for a specific deferrable block. The default value of a deferrable view is
+`Placeholder`, but you can also set the initial state while rendering the
+component.
+
+```typescript
+const {renderDeferBlock} = await render(FixtureComponent, {
+  deferBlockStates: DeferBlockState.Loading,
+})
+
+expect(screen.getByText(/loading/i)).toBeInTheDocument()
+
+await renderDeferBlock(DeferBlockState.Complete)
+expect(screen.getByText(/completed/i)).toBeInTheDocument()
+```

docs/angular-testing-library/version-compatibility.mdx

@@ -8,7 +8,8 @@ Library and Angular.
 
 | Angular | Angular Testing Library |
 | ------- | ----------------------- |
-| 16.x    | 13.x \|\| 14.x          |
-| >= 15.1 | 13.x \|\| 14.x          |
-| < 15.1  | 11.x \|\| 12.x          |
-| 14.x    | 11.x \|\| 12.x          |
+| 17.x    | 16.x, 15.x, 14.x, 13.x  |
+| 16.x    | 14.x, 13.x              |
+| >= 15.1 | 14.x, 13.x              |
+| < 15.1  | 12.x, 11.x              |
+| 14.x    | 12.x, 11.x              |

docs/dom-testing-library/install.mdx

@@ -28,6 +28,7 @@ install the wrapper:
 - [Puppeteer Testing Library](pptr-testing-library/intro.mdx)
 - [Testcafe Testing Library](testcafe-testing-library/intro.mdx)
 - [Nightwatch Testing Library](nightwatch-testing-library/intro.mdx)
+- [Solid Testing Library](solid-testing-library/intro.mdx)
 
 ## Ecosystem
 

docs/queries/about.mdx

@@ -317,12 +317,9 @@ can contain options that affect the precision of string matching:
 
 - `exact`: Defaults to `true`; matches full strings, case-sensitive. When false,
   matches substrings and is not case-sensitive.
-  - `exact` has no effect on `regex` or `function` arguments.
-  - `exact` has no effect on accessible names specified with the `name` option
-    of `*byRole` queries. You can use a regex for fuzzy matching on accessible
-    names.
-  - In most cases using a regex instead of a string gives you more control over
-    fuzzy matching and should be preferred over `{ exact: false }`.
+  - it has no effect when used together with `regex` or `function` arguments.
+  - in most cases, using a regex instead of a string combined with `{ exact: false }`
+    gives you more control over fuzzy matching so it should be preferred.
 - `normalizer`: An optional function which overrides normalization behavior. See
   [`Normalization`](#normalization).
 

docs/queries/byrole.mdx

@@ -462,3 +462,20 @@ You can query a specific element like this
 ```js
 getByRole('alertdialog', {description: 'Your session is about to expire'})
 ```
+
+## Performance
+
+`getByRole` is the most preferred query to use as it most closely resembles the
+user experience, however the calculations it must perform to provide this
+confidence can be expensive (particularly with large DOM trees).
+
+Where test performance is a concern it may be desirable to trade some of this
+confidence for improved performance.
+
+`getByRole` performance can be improved by setting the option
+[`hidden`](#hidden) to `true` and thereby avoid expensive visibility checks.
+Note that in doing so inaccessible elements will now be included in the result.
+
+Another option may be to substitute `getByRole` for simpler `getByLabelText` and
+`getByText` queries which can be significantly faster though less robust
+alternatives.

docs/react-testing-library/api.mdx

@@ -32,6 +32,8 @@ as these methods:
   - [`result`](#result)
   - [`rerender`](#rerender-1)
   - [`unmount`](#unmount-1)
+- [`configure`](#configure)
+- [`configure` Options](#configure-options)
 
 ---
 
@@ -105,6 +107,12 @@ your components.
 
 ### `legacyRoot`
 
+:::warning
+
+This option is only available when tests run with React 18 and earlier.
+
+:::
+
 By default we'll render with support for concurrent features (i.e.
 [`ReactDOMClient.createRoot`](https://reactjs.org/docs/react-dom-client.html#createroot)).
 However, if you're dealing with a legacy app that requires rendering like in
@@ -338,7 +346,7 @@ function renderHook<
   Props,
   Q extends Queries = typeof queries,
   Container extends Element | DocumentFragment = HTMLElement,
-  BaseElement extends Element | DocumentFragment = Container,
+  BaseElement extends Element | DocumentFragment = Container
 >(
   render: (initialProps: Props) => Result,
   options?: RenderHookOptions<Props, Q, Container, BaseElement>,
@@ -451,3 +459,23 @@ const {unmount} = renderHook(({name = 'Alice'} = {}) => name)
 
 unmount()
 ```
+
+## `configure`
+
+Changes global options. Basic usage can be seen at
+[Configuration Options](dom-testing-library/api-configuration.mdx).
+
+React Testing Library also has dedicated options.
+
+```typescript
+import {configure} from '@testing-library/react'
+
+configure({reactStrictMode: true})
+```
+
+## `configure` Options
+
+### `reactStrictMode`
+
+When enabled, [`<StrictMode>`](https://react.dev/reference/react/StrictMode) is
+rendered around the inner element. Defaults to `false`.

docs/react-testing-library/cheatsheet.mdx

@@ -131,7 +131,7 @@ See [Events API](dom-testing-library/api-events.mdx)
 ## Other
 
 See [Querying Within Elements](dom-testing-library/api-within.mdx),
-[Config API](dom-testing-library/api-configuration.mdx),
+[Config API](react-testing-library/api.mdx#configure),
 [Cleanup](react-testing-library/api.mdx#cleanup),
 
 - **within** take a node and return an object with all the queries bound to the

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

@@ -65,17 +65,24 @@ 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"
 import React from 'react'
-import {rest} from 'msw'
+import {http, HttpResponse} from 'msw'
 import {setupServer} from 'msw/node'
 import {render, fireEvent, screen} from '@testing-library/react'
 import '@testing-library/jest-dom'
 import Fetch from '../fetch'
 
 const server = setupServer(
-  rest.get('/greeting', (req, res, ctx) => {
-    return res(ctx.json({greeting: 'hello there'}))
+  http.get('/greeting', () => {
+    return HttpResponse.json({greeting: 'hello there'})
   }),
 )
 
@@ -96,8 +103,8 @@ test('loads and displays greeting', async () => {
 
 test('handles server error', async () => {
   server.use(
-    rest.get('/greeting', (req, res, ctx) => {
-      return res(ctx.status(500))
+    http.get('/greeting', () => {
+      return new HttpResponse(null, {status: 500})
     }),
   )
 
@@ -112,10 +119,6 @@ test('handles server error', async () => {
 })
 ```
 
-> We recommend using [Mock Service Worker](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.
-
 ---
 
 ## Step-By-Step
@@ -127,7 +130,7 @@ test('handles server error', async () => {
 import React from 'react'
 
 // import API mocking utilities from Mock Service Worker
-import {rest} from 'msw'
+import {http, HttpResponse} from 'msw'
 import {setupServer} from 'msw/node'
 
 // import react-testing methods
@@ -156,9 +159,9 @@ component makes.
 // declare which API requests to mock
 const server = setupServer(
   // capture "GET /greeting" requests
-  rest.get('/greeting', (req, res, ctx) => {
+  http.get('/greeting', (req, res, ctx) => {
     // respond using a mocked JSON body
-    return res(ctx.json({greeting: 'hello there'}))
+    return HttpResponse.json({greeting: 'hello there'})
   }),
 )
 
@@ -176,8 +179,8 @@ test('handles server error', async () => {
   server.use(
     // override the initial "GET /greeting" request handler
     // to return a 500 Server Error
-    rest.get('/greeting', (req, res, ctx) => {
-      return res(ctx.status(500))
+    http.get('/greeting', (req, res, ctx) => {
+      return new HttpResponse(null, {status: 500})
     }),
   )
 

docs/react-testing-library/intro.mdx

@@ -7,15 +7,20 @@ sidebar_label: Introduction
 [`React Testing Library`][gh] builds on top of `DOM Testing Library` by adding
 APIs for working with React components.
 
-> Projects created with [`Create React App`](https://create-react-app.dev/) have
-> out of the box support for **React Testing Library**. If that is not the case,
-> you can add it via `npm` like so:
+## Installation
 
 ```bash npm2yarn
 npm install --save-dev @testing-library/react
 ```
 
-- [React Testing Library on GitHub][gh]
+### With TypeScript
+
+To get full type coverage, you need to install the types for `react` and `react-dom` as well:
+
+```bash npm2yarn
+npm install --save-dev @testing-library/react @types/react-dom @types/react
+```
+
 
 [gh]: https://github.com/testing-library/react-testing-library