docs: v13 docs & migration guide (#1709)

website/docs/12.x/docs/api/misc/async.mdx

@@ -101,7 +101,7 @@ In order to properly use `waitFor` you need at least React >=16.9.0 (featuring a
 :::
 
 :::note
-If you receive warnings related to `act()` function consult our [Undestanding Act](docs/advanced/understanding-act.md) function document.
+If you receive warnings related to `act()` function consult our [Understanding Act](docs/advanced/understanding-act.md) function document.
 :::
 
 ## `waitForElementToBeRemoved`
@@ -134,5 +134,5 @@ In order to properly use `waitForElementToBeRemoved` you need at least React >=1
 :::
 
 :::note
-If you receive warnings related to `act()` function consult our [Undestanding Act](docs/advanced/understanding-act.md) function document.
+If you receive warnings related to `act()` function consult our [Understanding Act](docs/advanced/understanding-act.md) function document.
 :::

website/docs/12.x/docs/api/misc/config.mdx

@@ -27,7 +27,7 @@ This option is also available as `defaultHidden` alias for compatibility with [R
 
 Default [debug options](#debug) to be used when calling `debug()`. These default options will be overridden by the ones you specify directly when calling `debug()`.
 
-### `concurrentRoot` option
+### `concurrentRoot` option {#concurrent-root}
 
 Set to `true` to enable concurrent rendering used in the React Native New Architecture. Otherwise `render` will default to legacy synchronous rendering.
 

website/docs/12.x/docs/api/misc/other.mdx

@@ -31,7 +31,7 @@ Use cases for scoped queries include:
 
 Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]).
 
-Consult our [Undestanding Act function](docs/advanced/understanding-act.md) document for more understanding of its intricacies.
+Consult our [Understanding Act function](docs/advanced/understanding-act.md) document for more understanding of its intricacies.
 
 ## `cleanup`
 

website/docs/12.x/docs/api/render.mdx

@@ -32,7 +32,7 @@ wrapper?: React.ComponentType<any>,
 
 This option allows you to wrap the tested component, passed as the first option to the `render()` function, in an additional wrapper component. This is useful for creating reusable custom render functions for common React Context providers.
 
-#### `concurrentRoot` option
+#### `concurrentRoot` option {#concurrent-root}
 
 Set to `true` to enable concurrent rendering used in the React Native New Architecture. Otherwise `render` will default to legacy synchronous rendering.
 

website/docs/13.x-alpha/docs/api/misc/async.mdx → website/docs/13.x-next/docs/api/misc/async.mdx

@@ -53,12 +53,6 @@ Avoiding side effects in `expectation` callback can be partially enforced with t
 
 It is also recommended to have a [single assertion per each `waitFor`](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#having-multiple-assertions-in-a-single-waitfor-callback) for more consistency and faster failing tests. If you want to make several assertions, then they should be in seperate `waitFor` calls. In many cases you won't actually need to wrap the second assertion in `waitFor` since the first one will do the waiting required for asynchronous change to happen.
 
-### Using a React Native version < 0.71 with Jest fake timers
-
-:::caution
-When using a version of React Native < 0.71 and modern fake timers (the default for `Jest` >= 27), `waitFor` won't work (it will always timeout even if `expectation()` doesn't throw) unless you use the custom [@testing-library/react-native preset](https://github.com/callstack/react-native-testing-library#custom-jest-preset).
-:::
-
 `waitFor` checks whether Jest fake timers are enabled and adapts its behavior in such case. The following snippet is a simplified version of how it behaves when fake timers are enabled:
 
 ```tsx
@@ -96,12 +90,8 @@ await waitFor(() => {
 }, 10000);
 ```
 
-:::info
-In order to properly use `waitFor` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0).
-:::
-
 :::note
-If you receive warnings related to `act()` function consult our [Undestanding Act](docs/advanced/understanding-act.md) function document.
+If you receive warnings related to `act()` function consult our [Understanding Act](docs/advanced/understanding-act.md) function document.
 :::
 
 ## `waitForElementToBeRemoved`
@@ -129,10 +119,6 @@ This method expects that the element is initially present in the render tree and
 
 You can use any of `getBy`, `getAllBy`, `queryBy` and `queryAllBy` queries for `expectation` parameter.
 
-:::info
-In order to properly use `waitForElementToBeRemoved` you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0).
-:::
-
 :::note
-If you receive warnings related to `act()` function consult our [Undestanding Act](docs/advanced/understanding-act.md) function document.
+If you receive warnings related to `act()` function consult our [Understanding Act](docs/advanced/understanding-act.md) function document.
 :::

website/docs/13.x-alpha/docs/api/misc/config.mdx → website/docs/13.x-next/docs/api/misc/config.mdx

@@ -27,7 +27,7 @@ This option is also available as `defaultHidden` alias for compatibility with [R
 
 Default [debug options](#debug) to be used when calling `debug()`. These default options will be overridden by the ones you specify directly when calling `debug()`.
 
-### `concurrentRoot` option
+### `concurrentRoot` option {#concurrent-root}
 
 Set to `false` to disable concurrent rendering.
 Otherwise, `render` will default to using concurrent rendering used in the React Native New Architecture.

website/docs/13.x-alpha/docs/api/misc/other.mdx → website/docs/13.x-next/docs/api/misc/other.mdx

@@ -31,7 +31,7 @@ Use cases for scoped queries include:
 
 Useful function to help testing components that use hooks API. By default any `render`, `update`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually. This method is re-exported from [`react-test-renderer`](https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactTestRenderer.js#L567]).
 
-Consult our [Undestanding Act function](docs/advanced/understanding-act.md) document for more understanding of its intricacies.
+Consult our [Understanding Act function](docs/advanced/understanding-act.md) document for more understanding of its intricacies.
 
 ## `cleanup`
 

website/docs/13.x-alpha/docs/api/queries.mdx → website/docs/13.x-next/docs/api/queries.mdx

@@ -383,115 +383,6 @@ const element = screen.getByTestId('unique-id');
 In the spirit of [the guiding principles](https://testing-library.com/docs/guiding-principles), it is recommended to use this only after the other queries don't work for your use case. Using `testID` attributes do not resemble how your software is used and should be avoided if possible. However, they are particularly useful for end-to-end testing on real devices, e.g. using Detox and it's an encouraged technique to use there. Learn more from the blog post ["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change).
 :::
 
-### `*ByA11yState`, `ByAccessibilityState` (deprecated) {#by-accessibility-state}
-
-:::caution
-This query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
-
-- [`*ByRole`](#by-role) query with relevant state options: `disabled`, `selected`, `checked`, `expanded` and `busy`
-- use built-in Jest matchers to check the state of element found using some other query:
-  - enabled state: [`toBeEnabled()` / `toBeDisabled()`](docs/api/jest-matchers#tobeenabled)
-  - checked state: [`toBeChecked()` / `toBePartiallyChecked()`](docs/api/jest-matchers#tobechecked)
-  - selected state: [`toBeSelected()`](docs/api/jest-matchers#tobeselected)
-  - expanded state: [`toBeExpanded()` / `toBeCollapsed()`](docs/api/jest-matchers#tobeexpanded)
-  - busy state: [`toBeBusy()`](docs/api/jest-matchers#tobebusy)
-
-:::
-
-> getByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState, findByA11yState, findAllByA11yState
-> getByAccessibilityState, getAllByAccessibilityState, queryByAccessibilityState, queryAllByAccessibilityState, findByAccessibilityState, findAllByAccessibilityState
-
-```ts
-getByA11yState(
-  state: {
-    disabled?: boolean,
-    selected?: boolean,
-    checked?: boolean | 'mixed',
-    busy?: boolean,
-    expanded?: boolean,
-  },
-  options?: {
-    includeHiddenElements?: boolean;
-  },
-): ReactTestInstance;
-```
-
-Returns a `ReactTestInstance` with matching `accessibilityState` prop or ARIA state props: `aria-disabled`, `aria-selected`, `aria-checked`, `aria-busy`, and `aria-expanded`.
-
-```jsx
-import { render, screen } from '@testing-library/react-native';
-
-render(<Component />);
-const element = screen.getByA11yState({ disabled: true });
-```
-
-:::note
-
-#### Default state for: `disabled`, `selected`, and `busy` keys
-
-Passing `false` matcher value will match both elements with explicit `false` state value and without explicit state value.
-
-For instance, `getByA11yState({ disabled: false })` will match elements with following props:
-
-- `accessibilityState={{ disabled: false, ... }}`
-- no `disabled` key under `accessibilityState` prop, e.g. `accessibilityState={{}}`
-- no `accessibilityState` prop at all
-
-#### Default state for: `checked` and `expanded` keys
-
-Passing `false` matcher value will only match elements with explicit `false` state value.
-
-For instance, `getByA11yState({ checked: false })` will only match elements with:
-
-- `accessibilityState={{ checked: false, ... }}`
-
-but will not match elements with following props:
-
-- no `checked` key under `accessibilityState` prop, e.g. `accessibilityState={{}}`
-- no `accessibilityState` prop at all
-
-The difference in handling default values is made to reflect observed accessibility behaviour on iOS and Android platforms.
-:::
-
-### `*ByA11yValue`, `*ByAccessibilityValue` (deprecated) {#by-accessibility-value}
-
-:::caution
-This query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
-
-- [`toHaveAccessibilityValue()`](docs/api/jest-matchers#tohaveaccessibilityvalue) Jest matcher to check the state of element found using some other query
-- [`*ByRole`](#by-role) query with `value` option
-
-:::
-
-> getByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue, findByA11yValue, findAllByA11yValue
-> getByAccessibilityValue, getAllByAccessibilityValue, queryByAccessibilityValue, queryAllByAccessibilityValue, findByAccessibilityValue, findAllByAccessibilityValue
-
-```ts
-getByA11yValue(
-  value: {
-    min?: number;
-    max?: number;
-    now?: number;
-    text?: TextMatch;
-  },
-  options?: {
-    includeHiddenElements?: boolean;
-  },
-): ReactTestInstance;
-```
-
-Returns a host element with matching accessibility value based on `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` & `accessibilityValue` props. Only value entires provided to the query will be used to match elements. Element might have additional accessibility value entries and still be matched.
-
-When querying by `text` entry a string or regex might be used.
-
-```jsx
-import { render, screen } from '@testing-library/react-native';
-
-render(<View accessibilityValue={{ min: 0, max: 100, now: 25, text: '25%' }} />);
-const element = screen.getByA11yValue({ now: 25 });
-const element2 = screen.getByA11yValue({ text: /25/ });
-```
-
 ### Common options
 
 Usually query first argument can be a **string** or a **regex**. All queries take at least the [`hidden`](#hidden-option) option as an optionnal second argument and some queries accept more options which change string matching behaviour. See [TextMatch](#textmatch) for more info.

website/docs/13.x-alpha/docs/api/render.mdx → website/docs/13.x-next/docs/api/render.mdx

@@ -32,7 +32,7 @@ wrapper?: React.ComponentType<any>,
 
 This option allows you to wrap the tested component, passed as the first option to the `render()` function, in an additional wrapper component. This is useful for creating reusable custom render functions for common React Context providers.
 
-#### `concurrentRoot` option
+#### `concurrentRoot` option {#concurrent-root}
 
 Set to `false` to disable concurrent rendering.
 Otherwise, `render` will default to using concurrent rendering used in the React Native New Architecture.

website/docs/13.x-next/docs/migration/_meta.json

@@ -0,0 +1 @@
+["v13", { "type": "dir", "name": "previous", "label": "Previous versions", "collapsed": true }]

website/docs/13.x-next/docs/migration/previous/_meta.json

@@ -0,0 +1 @@
+["v12", "jest-matchers", "v11", "v9", "v7", "v2"]

website/docs/13.x-next/docs/migration/v13.mdx

@@ -0,0 +1,122 @@
+# Migration to 13.x
+
+This guide describes the migration to React Native Testing Library version 13 from version 12.x.
+
+Overall, the v13 release is relatively small, focusing on removing deprecated queries and improving the developer experience.
+
+## Breaking changes
+
+### Supported React and React Native versions
+
+This version supports only React 18+ and corresponding React Native versions (0.71+). If you use React 16 or 17, please use the latest of v12 versions.
+
+Note: currently, stable React Native is unavailable for React 19, which is still in the RC phase, so we test against React Native nightly builds.
+
+### Concurrent rendering by default
+
+This version introduces concurrent rendering by default. This change should not affect regular tests, but it might affect your tests if you use React Suspense or similar.
+
+You can revert to legacy rendering by passing `concurrentRoot: false` to [render](docs/api/render#concurrent-root) or [configure](docs/api/misc/config#concurrent-root) methods.
+
+Note: in React 19, concurrent rendering is the only supported rendering mode.
+
+### Extend Jest matchers by default
+
+You can remove `import '@testing-library/react-native/extend-expect'` imports, as now Jest matchers are extended by default when you import anything from `@testing-library/react-native`.
+
+You can avoid the automatic extending of Jest matchers by importing `@testing-library/react-native/pure` instead.
+
+```tsx title=jest-setup.ts
+// Remove this:
+import '@testing-library/react-native/extend-expect';
+```
+
+### Removed deprecated `*ByAccessibilityState` queries
+
+We have removed this deprecated query as it is typically too general to give meaningful results. Use one of the following options:
+
+- [\*ByRole](#by-role) query with relevant state options: `disabled`, `selected`, `checked`, `expanded` and `busy`
+- use built-in Jest matchers to check the state of element found using some other query:
+  - enabled state: [toBeEnabled() / toBeDisabled()](docs/api/jest-matchers#tobeenabled)
+  - checked state: [toBeChecked() / toBePartiallyChecked()](docs/api/jest-matchers#tobechecked)
+  - selected state: [toBeSelected()](docs/api/jest-matchers#tobeselected)
+  - expanded state: [toBeExpanded() / toBeCollapsed()](docs/api/jest-matchers#tobeexpanded)
+  - busy state: [toBeBusy()](docs/api/jest-matchers#tobebusy)
+
+```ts
+// Replace this:
+const view = screen.getByAccessibilityState({ disabled: true });
+
+// with this (getByRole query):
+const view = screen.getByRole('<proper role here>', { disabled: true });
+
+// or this (Jest matcher):
+const view = screen.getBy*(...); // Find the element using any query: *ByRole, *ByText, *ByTestId
+expect(view).toBeDisabled(); // Assert its accessibility state
+```
+
+### Removed deprecated `*ByAccessibilityValue` queries
+
+We have removed this deprecated query as it is typically too general to give meaningful results. Use one of the following options:
+
+- [toHaveAccessibilityValue()](docs/api/jest-matchers#tohaveaccessibilityvalue) Jest matcher to check the state of element found using some other query
+- [\*ByRole](#by-role) query with `value` option
+
+```ts
+// Replace this:
+const view = screen.getByAccessibilityValue({ now: 50, min: 0, max: 50 });
+
+// with this (getByRole query):
+const view = screen.getByRole('<proper role here>', { value: { now: 50, min: 0, max: 50 } });
+
+// or this (Jest matcher):
+const view = screen.getBy*(...); // Find the element using any query: *ByRole, *ByText, *ByTestId
+expect(view).toHaveAccessibilityValue({ now: 50, min: 0, max: 50 }); // Assert its accessibility value
+```
+
+### Removed Jest preset
+
+We have removed RNTL Jest preset, so you should change you `jest.config.js` accordingly.
+
+Replace:
+
+```ts title=jest.config.js
+// replace this:
+preset: '@testing-library/react-native';
+
+// with this:
+preset: 'react-native';
+```
+
+### Removed `debug.shallow`
+
+We didn't support shallow rendering for the time being. Now, we are removing the last remains of it: `debug.shallow()`. If you are interested in shallow rendering see [here](docs/migration/previous/v2#removed-global-shallow-function).
+
+### Changes to accessibility label calculation
+
+Explicit labels:
+
+- `accessiblityLabelledBy`
+- `accessiblityLabel`
+- `aria-labelledby`
+- `aria-label`
+
+now take strict priority over implicit labels derived from the element's text content.
+
+## Other changes
+
+### Removed host component names autodetection
+
+This change should not break any tests, it should also make RNTL tests run 10-20% faster.
+
+### Use React implementation of `act` instead of React Test Renderer one
+
+This change should not break any tests.
+
+### Updated `flushMicroTasks` internal method
+
+This change should not break any tests.
+
+## Full Changelog
+
+https://github.com/callstack/react-native-testing-library/compare/v12.8.1...v13.0.0-beta.0

website/rspress.config.ts

@@ -19,7 +19,7 @@ export default defineConfig({
   },
   multiVersion: {
     default: '12.x',
-    versions: ['12.x', '13.x-alpha'],
+    versions: ['12.x', '13.x-next'],
   },
   route: {
     cleanUrls: true,