diff --git a/README.md b/README.md
index 3d3670a81..9ea44e1e7 100644
--- a/README.md
+++ b/README.md
@@ -119,13 +119,16 @@ You can find the source of `QuestionsBoard` component and this example [here](ht
## API / Usage
-The [public API](https://callstack.github.io/react-native-testing-library/docs/api) of `@testing-library/react-native` is focused around these essential methods:
-
-- [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) – deeply renders the given React element and returns helpers to query the output components.
-- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/api#fireevent) - invokes named event handler on the element.
-- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/api#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out.
-- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/api#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out.
-- [`within`](https://callstack.github.io/react-native-testing-library/docs/api#within) - creates a queries object scoped for a given element.
+The public API of `@testing-library/react-native` is focused around these essential APIs:
+
+- [`render`](https://callstack.github.io/react-native-testing-library/docs/render) – renders the given React element
+- [`screen`](https://callstack.github.io/react-native-testing-library/docs/screen) – queries for looking up rendered elements, as well as some useful helpers.
+- [`userEvent`](https://callstack.github.io/react-native-testing-library/docs/user-event) - realistic simulation of user interaction with elements like buttons and text inputs.
+- [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/fire-event) - general purpose event simulation.
+- [Jest matchers](https://callstack.github.io/react-native-testing-library/docs/jest-matchers) - validate assumptions about your components.
+- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/other#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out.
+- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/other#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out.
+- [`within`](https://callstack.github.io/react-native-testing-library/docs/other#within) - creates a queries object scoped for a given element.
## Migration Guides
diff --git a/src/__tests__/questionsBoard.test.tsx b/src/__tests__/questionsBoard.test.tsx
index 5776ebb40..d3faa72bd 100644
--- a/src/__tests__/questionsBoard.test.tsx
+++ b/src/__tests__/questionsBoard.test.tsx
@@ -46,12 +46,8 @@ test('form submits two answers', async () => {
render();
const answerInputs = screen.getAllByLabelText('answer input');
-
- // simulates the user focusing on TextInput and typing text one char at a time
await user.type(answerInputs[0], 'a1');
await user.type(answerInputs[1], 'a2');
-
- // simulates the user pressing on any pressable element
await user.press(screen.getByRole('button', { name: 'Submit' }));
expect(onSubmit).toHaveBeenCalledWith({
diff --git a/website/docs/API.md b/website/docs/API.md
deleted file mode 100644
index 58dc81e13..000000000
--- a/website/docs/API.md
+++ /dev/null
@@ -1,835 +0,0 @@
----
-id: api
-title: API
----
-
-import TOCInline from '@theme/TOCInline';
-
-
-
-## `render` API
-
-- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/render.test.tsx)
-
-Defined as:
-
-```jsx
-function render(
- component: React.Element,
- options?: RenderOptions
-): RenderResult {}
-```
-
-Deeply renders given React element and returns helpers to query the output components structure.
-
-```jsx
-import { render } from '@testing-library/react-native';
-import { QuestionsBoard } from '../QuestionsBoard';
-
-test('should verify two questions', () => {
- render();
- const allQuestions = screen.queryAllByRole('header');
-
- expect(allQuestions).toHaveLength(2);
-});
-```
-
-> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases it's convenient to create your custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render).
-
-The `render` method returns a `RenderResult` object having properties described below.
-
-:::info
-Latest `render` result is kept in [`screen`](#screen) variable that can be imported from `@testing-library/react-native` package.
-
-Using `screen` instead of destructuring `render` result is recommended approach. See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details.
-:::
-
-### Options {#render-options}
-
-The behavior of `render` method can be customized by passing various options as a second argument of `RenderOptions` type:
-
-#### `wrapper` option
-
-```ts
-wrapper?: React.ComponentType,
-```
-
-This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common React Context providers.
-
-#### `createNodeMock` option
-
-```ts
-createNodeMock?: (element: React.Element) => any,
-```
-
-This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas).
-
-#### `unstable_validateStringsRenderedWithinText` option
-
-```ts
-unstable_validateStringsRenderedWithinText?: boolean;
-```
-
-:::note
-This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes.
-:::
-
-This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``.
-
-This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests.
-
-### `...queries`
-
-The most important feature of `render` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy.
-
-See [Queries](./Queries.md) for a complete list.
-
-#### Example
-
-```jsx
-import { render } from '@testing-library/react-native';
-
-const { getByText, queryByA11yState } = render();
-```
-
-### `update`
-
-_Also available under `rerender` alias_
-
-```ts
-update(element: React.Element): void
-rerender(element: React.Element): void
-```
-
-Re-render the in-memory tree with a new root element. This simulates a React update at the root. If the new element has the same type and key as the previous element, the tree will be updated; otherwise, it will re-mount a new tree. This is useful when testing for `componentDidUpdate` behavior, by passing updated props to the component.
-
-[Example code](https://github.com/callstack/react-native-testing-library/blob/f96d782d26dd4815dbfd01de6ef7a647efd1f693/src/__tests__/act.test.js#L31-L37)
-
-### `unmount`
-
-```ts
-unmount(): void
-```
-
-Unmount the in-memory tree, triggering the appropriate lifecycle events.
-
-:::note
-Usually you should not need to call `unmount` as it is done automatically if your test runner supports `afterEach` hook (like Jest, mocha, Jasmine).
-:::
-
-### `debug`
-
-```ts
-interface DebugOptions {
- message?: string;
- mapProps?: MapPropsFunction;
-}
-
-debug(options?: DebugOptions | string): void
-```
-
-Pretty prints deeply rendered component passed to `render`.
-
-#### `message` option
-
-You can provide a message that will be printed on top.
-
-```jsx
-render();
-screen.debug({ message: 'optional message' });
-```
-
-logs optional message and colored JSX:
-
-```jsx
-optional message
-
-
- Press me
-
-```
-
-#### `mapProps` option
-
-You can use the `mapProps` option to transform the props that will be printed :
-
-```jsx
-render();
-debug({ mapProps: ({ style, ...props }) => ({ props }) });
-```
-
-This will log the rendered JSX without the `style` props.
-
-The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out.
-
-```ts
-debug({ mapProps: (props) => ({}) });
-```
-
-This option can be used to target specific props when debugging a query (for instance keeping only `children` prop when debugging a `getByText` query).
-
-You can also transform prop values so that they are more readable (e.g. flatten styles).
-
-```ts
-import { StyleSheet } from 'react-native';
-
-debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) });
-```
-
-Or remove props that have little value when debugging tests, e.g. path prop for svgs
-
-```ts
-debug({ mapProps: ({ path, ...props }) => ({ ...props }) });
-```
-
-#### `debug.shallow`
-
-Pretty prints shallowly rendered component passed to `render` with optional message on top.
-
-### `toJSON`
-
-```ts
-toJSON(): ReactTestRendererJSON | null
-```
-
-Get the rendered component JSON representation, e.g. for snapshot testing.
-
-### `root`
-
-```ts
-root: ReactTestInstance;
-```
-
-Returns the rendered root [host element](testing-env#host-and-composite-components).
-
-This API is primarily useful in component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods.
-
-### `UNSAFE_root`
-
-```ts
-UNSAFE_root: ReactTestInstance;
-```
-
-Returns the rendered [composite root element](testing-env#host-and-composite-components).
-
-:::caution
-This API typically will return a composite view which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing.
-:::
-
-:::note
-This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/api#container-1). However, despite the same name, the actual behavior has been signficantly different, hence the name change to `UNSAFE_root`.
-:::
-
-## `screen` API
-
-```ts
-let screen: RenderResult;
-```
-
-Hold the value of latest render call for easier access to query and other functions returned by [`render`](#render).
-
-Its value is automatically cleared after each test by calling [`cleanup`](#cleanup). If no `render` call has been made in a given test then it holds a special object that implements `RenderResult` but throws a helpful error on each property and method access.
-
-This can also be used to build test utils that would normally require to be in render scope, either in a test file or globally for your project. For instance:
-
-```ts
-// Prints the rendered components omitting all props except children.
-const debugText = () => screen.debug({ mapProps: (props) => ({}) });
-```
-
-## `fireEvent` API
-
-```ts
-function fireEvent(
- element: ReactTestInstance,
- eventName: string,
- ...data: Array
-): void {}
-```
-
-:::note
-For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers
-more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior.
-
-Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components.
-:::
-
-`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed.
-
-Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object.
-
-```jsx
-import { render, screen, fireEvent } from '@testing-library/react-native';
-
-test('fire changeText event', () => {
- const onEventMock = jest.fn();
- render(
- // MyComponent renders TextInput which has a placeholder 'Enter details'
- // and with `onChangeText` bound to handleChangeText
- ,
- );
-
- fireEvent(screen.getByPlaceholderText('change'), 'onChangeText', 'ab');
- expect(onEventMock).toHaveBeenCalledWith('ab');
-});
-```
-
-:::note
-Please note that from version `7.0` `fireEvent` performs checks that should prevent events firing on disabled elements.
-:::
-
-An example using `fireEvent` with native events that aren't already aliased by the `fireEvent` api.
-
-```jsx
-import { TextInput, View } from 'react-native';
-import { fireEvent, render } from '@testing-library/react-native';
-
-const onBlurMock = jest.fn();
-
-render(
-
-
- ,
-);
-
-// you can omit the `on` prefix
-fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur');
-```
-
-FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`.
-
-### `fireEvent.press`
-
-```
-fireEvent.press: (element: ReactTestInstance, ...data: Array) => void
-```
-
-:::note
-It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support.
-:::
-
-Invokes `press` event handler on the element or parent element in the tree.
-
-```jsx
-import { View, Text, TouchableOpacity } from 'react-native';
-import { render, screen, fireEvent } from '@testing-library/react-native';
-
-const onPressMock = jest.fn();
-const eventData = {
- nativeEvent: {
- pageX: 20,
- pageY: 30,
- },
-};
-
-render(
-
-
- Press me
-
- ,
-);
-
-fireEvent.press(screen.getByText('Press me'), eventData);
-expect(onPressMock).toHaveBeenCalledWith(eventData);
-```
-
-### `fireEvent.changeText`
-
-```
-fireEvent.changeText: (element: ReactTestInstance, ...data: Array) => void
-```
-
-:::note
-It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events.
-:::
-
-Invokes `changeText` event handler on the element or parent element in the tree.
-
-```jsx
-import { View, TextInput } from 'react-native';
-import { render, screen, fireEvent } from '@testing-library/react-native';
-
-const onChangeTextMock = jest.fn();
-const CHANGE_TEXT = 'content';
-
-render(
-
-
- ,
-);
-
-fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT);
-```
-
-### `fireEvent.scroll`
-
-```
-fireEvent.scroll: (element: ReactTestInstance, ...data: Array) => void
-```
-
-Invokes `scroll` event handler on the element or parent element in the tree.
-
-#### On a `ScrollView`
-
-```jsx
-import { ScrollView, Text } from 'react-native';
-import { render, screen, fireEvent } from '@testing-library/react-native';
-
-const onScrollMock = jest.fn();
-const eventData = {
- nativeEvent: {
- contentOffset: {
- y: 200,
- },
- },
-};
-
-render(
-
- XD
- ,
-);
-
-fireEvent.scroll(screen.getByText('scroll-view'), eventData);
-```
-
-:::note
-
-Prefer using [`user.scrollTo`](./UserEvent.md#scrollto) over `fireEvent.scroll` for `ScrollView`, `FlatList`, and `SectionList` components. User Event provides a more realistic event simulation based on React Native runtime behavior.
-
-:::
-
-## Helper functions
-
-### `waitFor`
-
-- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for.test.tsx)
-
-Defined as:
-
-```jsx
-function waitFor(
- expectation: () => T,
- { timeout: number = 1000, interval: number = 50 },
-): Promise {}
-```
-
-Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function.
-
-```tsx
-await waitFor(() => expect(mockFunction).toHaveBeenCalledWith());
-```
-
-`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code.
-
-```tsx
-// ❌ `waitFor` will return immediately because callback does not throw
-await waitFor(() => false);
-```
-
-`waitFor` is an async function so you need to `await` the result to pause test execution.
-
-```jsx
-// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached
-waitFor(() => expect(1).toBe(2));
-```
-
-:::note
-You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library).
-:::
-
-Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`.
-
-```jsx
-await waitFor(() => {
- // ❌ button will be pressed on each waitFor iteration
- fireEvent.press(screen.getByText('press me'));
- expect(mockOnPress).toHaveBeenCalled();
-});
-```
-
-:::note
-Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md).
-:::
-
-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
-let fakeTimeRemaining = timeout;
-let lastError;
-
-while (fakeTimeRemaining > 0) {
- fakeTimeRemaining = fakeTimeRemaining - interval;
- jest.advanceTimersByTime(interval);
- try {
- // resolve
- return expectation();
- } catch (error) {
- lastError = error;
- }
-}
-
-// reject
-throw lastError;
-```
-
-In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us.
-
-```tsx
-// in component
-setTimeout(() => {
- someFunction();
-}, 10000);
-
-// in test
-jest.useFakeTimers();
-
-await waitFor(() => {
- expect(someFunction).toHaveBeenCalledWith();
-}, 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](./UnderstandingAct.md) function document.
-:::
-
-### `waitForElementToBeRemoved`
-
-- [`Example code`]https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/wait-for-element-to-be-removed.test.tsx)
-
-Defined as:
-
-```ts
-function waitForElementToBeRemoved(
- expectation: () => T,
- { timeout: number = 4500, interval: number = 50 },
-): Promise {}
-```
-
-Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not.
-
-```jsx
-import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native';
-
-test('waiting for an Banana to be removed', async () => {
- render();
-
- await waitForElementToBeRemoved(() => screen.getByText('Banana ready'));
-});
-```
-
-This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error.
-
-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](./UnderstandingAct.md) function document.
-:::
-
-### `within`, `getQueriesForElement`
-
-- [`Example code`](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/within.test.tsx)
-
-Defined as:
-
-```jsx
-function within(element: ReactTestInstance): Queries {}
-
-function getQueriesForElement(element: ReactTestInstance): Queries {}
-```
-
-`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element.
-
-:::note
-Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included.
-:::
-
-```jsx
-const detailsScreen = within(screen.getByA11yHint('Details Screen'));
-expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen();
-expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen();
-expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen();
-await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen();
-```
-
-Use cases for scoped queries include:
-
-- queries scoped to a single item inside a FlatList containing many items
-- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation)
-
-### `act`
-
-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](./UnderstandingAct.md) document for more understanding of its intricacies.
-
-### `cleanup`
-
-```ts
-const cleanup: () => void;
-```
-
-Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output.
-
-:::info
-Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test.
-:::
-
-For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so:
-
-```jsx
-import { cleanup, render } from '@testing-library/react-native/pure';
-import { View } from 'react-native';
-
-afterEach(cleanup);
-
-it('renders a view', () => {
- render();
- // ...
-});
-```
-
-The `afterEach(cleanup)` call also works in `describe` blocks:
-
-```jsx
-describe('when logged in', () => {
- afterEach(cleanup);
-
- it('renders the user', () => {
- render();
- // ...
- });
-});
-```
-
-Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).
-
-## `renderHook` API
-
-Defined as:
-
-```ts
-function renderHook(
- callback: (props?: Props) => Result,
- options?: RenderHookOptions,
-): RenderHookResult;
-```
-
-Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult-object) object, which you can interact with.
-
-```ts
-import { renderHook } from '@testing-library/react-native';
-import { useCount } from '../useCount';
-
-it('should increment count', () => {
- const { result } = renderHook(() => useCount());
-
- expect(result.current.count).toBe(0);
- act(() => {
- // Note that you should wrap the calls to functions your hook returns with `act` if they trigger an update of your hook's state to ensure pending useEffects are run before your next assertion.
- result.current.increment();
- });
- expect(result.current.count).toBe(1);
-});
-```
-
-```ts
-// useCount.js
-export const useCount = () => {
- const [count, setCount] = useState(0);
- const increment = () => setCount((previousCount) => previousCount + 1);
-
- return { count, increment };
-};
-```
-
-The `renderHook` function accepts the following arguments:
-
-Callback is a function that is called each `render` of the test component. This function should call one or more hooks for testing.
-
-The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call.
-
-### `options`
-
-A `RenderHookOptions` object to modify the execution of the `callback` function, containing the following properties:
-
-#### `initialProps`
-
-The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
-
-#### `wrapper`
-
-A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`.
-
-### `RenderHookResult`
-
-```ts
-interface RenderHookResult {
- result: { current: Result };
- rerender: (props: Props) => void;
- unmount: () => void;
-}
-```
-
-The `renderHook` function returns an object that has the following properties:
-
-### `result`
-
-The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call.
-
-### `rerender`
-
-A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
-
-### `unmount`
-
-A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks.
-
-### Examples
-
-Here we present some extra examples of using `renderHook` API.
-
-#### With `initialProps`
-
-```ts
-const useCount = (initialCount: number) => {
- const [count, setCount] = useState(initialCount);
- const increment = () => setCount((previousCount) => previousCount + 1);
-
- useEffect(() => {
- setCount(initialCount);
- }, [initialCount]);
-
- return { count, increment };
-};
-
-it('should increment count', () => {
- const { result, rerender } = renderHook((initialCount: number) => useCount(initialCount), {
- initialProps: 1,
- });
-
- expect(result.current.count).toBe(1);
-
- act(() => {
- result.current.increment();
- });
-
- expect(result.current.count).toBe(2);
- rerender(5);
- expect(result.current.count).toBe(5);
-});
-```
-
-#### With `wrapper`
-
-```tsx
-it('should use context value', () => {
- function Wrapper({ children }: { children: ReactNode }) {
- return {children};
- }
-
- const { result } = renderHook(() => useHook(), { wrapper: Wrapper });
- // ...
-});
-```
-
-## Configuration
-
-### `configure`
-
-```ts
-type Config = {
- asyncUtilTimeout: number;
- defaultHidden: boolean;
- defaultDebugOptions: Partial;
-};
-
-function configure(options: Partial) {}
-```
-
-#### `asyncUtilTimeout` option
-
-Default timeout, in ms, for async helper functions (`waitFor`, `waitForElementToBeRemoved`) and `findBy*` queries. Defaults to 1000 ms.
-
-#### `defaultIncludeHiddenElements` option
-
-Default value for [includeHiddenElements](Queries.md#includehiddenelements-option) query option for all queries. The default value is set to `false`, so all queries will not match [elements hidden from accessibility](#ishiddenfromaccessibility). This is because the users of the app would not be able to see such elements.
-
-This option is also available as `defaultHidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden).
-
-#### `defaultDebugOptions` option
-
-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()`.
-
-### `resetToDefaults()`
-
-```ts
-function resetToDefaults() {}
-```
-
-### Environment variables
-
-#### `RNTL_SKIP_AUTO_CLEANUP`
-
-Set to `true` to disable automatic `cleanup()` after each test. It works the same as importing `react-native-testing-library/dont-cleanup-after-each` or using `react-native-testing-library/pure`.
-
-```shell
-$ RNTL_SKIP_AUTO_CLEANUP=true jest
-```
-
-#### `RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS`
-
-Set to `true` to disable auto-detection of fake timers. This might be useful in rare cases when you want to use non-Jest fake timers. See [issue #886](https://github.com/callstack/react-native-testing-library/issues/886) for more details.
-
-```shell
-$ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest
-```
-
-## Accessibility
-
-### `isHiddenFromAccessibility`
-
-```ts
-function isHiddenFromAccessibility(
- element: ReactTestInstance | null
-): boolean {}
-```
-
-Also available as `isInaccessible()` alias for React Testing Library compatibility.
-
-Checks if given element is hidden from assistive technology, e.g. screen readers.
-
-:::note
-Like [`isInaccessible`](https://testing-library.com/docs/dom-testing-library/api-accessibility/#isinaccessible) function from DOM Testing Library this function considers both accessibility elements and presentational elements (regular `View`s) to be accessible, unless they are hidden in terms of host platform.
-
-This covers only part of [ARIA notion of Accessiblity Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), as ARIA excludes both hidden and presentational elements from the Accessibility Tree.
-:::
-
-For the scope of this function, element is inaccessible when it, or any of its ancestors, meets any of the following conditions:
-
-- it has `display: none` style
-- it has [`aria-hidden`](https://reactnative.dev/docs/accessibility#aria-hidden) prop set to `true`
-- it has [`accessibilityElementsHidden`](https://reactnative.dev/docs/accessibility#accessibilityelementshidden-ios) prop set to `true`
-- it has [`importantForAccessibility`](https://reactnative.dev/docs/accessibility#importantforaccessibility-android) prop set to `no-hide-descendants`
-- it has sibling host element with either [`aria-modal`](https://reactnative.dev/docs/accessibility#aria-modal-ios) or [`accessibilityViewIsModal`](https://reactnative.dev/docs/accessibility#accessibilityviewismodal-ios) prop set to `true`
-
-Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAccessibility="no"` props does not cause the element to become inaccessible.
diff --git a/website/docs/FAQ.md b/website/docs/FAQ.md
index 5bca63b71..f71810851 100644
--- a/website/docs/FAQ.md
+++ b/website/docs/FAQ.md
@@ -28,7 +28,7 @@ On the negative side:
- you cannot test native features
- it might not perfectly simulate certain JavaScript features, but we are working on it
-The [User Event interactions](user-event) solve some of the simulation issues, as they offer more realistic event handling than the basic [Fire Event API](api#fireevent-api).
+The [User Event interactions](user-event) solve some of the simulation issues, as they offer more realistic event handling than the basic [Fire Event API](fire-event).
### Should I use/migrate to `screen` queries?
@@ -39,4 +39,4 @@ For new code, you are encouraged to use `screen` as there are some good reasons
### Should I use/migrate to User Event interactions?
-We encourage you to migrate existing tests to use the [User Event interactions](user-event), which offer more realistic event handling than the basic [Fire Event API](api#fireevent-api). Hence, it will provide more confidence in the quality of your code.
+We encourage you to migrate existing tests to use the [User Event interactions](user-event), which offer more realistic event handling than the basic [Fire Event API](fire-event). Hence, it will provide more confidence in the quality of your code.
diff --git a/website/docs/FireEvent.md b/website/docs/FireEvent.md
new file mode 100644
index 000000000..120839480
--- /dev/null
+++ b/website/docs/FireEvent.md
@@ -0,0 +1,166 @@
+---
+id: fire-event
+title: Fire Event
+---
+
+```ts
+function fireEvent(
+ element: ReactTestInstance,
+ eventName: string,
+ ...data: Array
+): void
+```
+
+:::note
+For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers
+more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior.
+
+Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components.
+:::
+
+The `fireEvent` API allows you to trigger all kinds of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed.
+
+Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object.
+
+```jsx
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+test('fire changeText event', () => {
+ const onEventMock = jest.fn();
+ render(
+ // MyComponent renders TextInput which has a placeholder 'Enter details'
+ // and with `onChangeText` bound to handleChangeText
+ ,
+ );
+
+ fireEvent(screen.getByPlaceholderText('change'), 'onChangeText', 'ab');
+ expect(onEventMock).toHaveBeenCalledWith('ab');
+});
+```
+
+:::note
+Please note that from version `7.0` `fireEvent` performs checks that should prevent events firing on disabled elements.
+:::
+
+An example using `fireEvent` with native events that aren't already aliased by the `fireEvent` api.
+
+```jsx
+import { TextInput, View } from 'react-native';
+import { fireEvent, render } from '@testing-library/react-native';
+
+const onBlurMock = jest.fn();
+
+render(
+
+
+ ,
+);
+
+// you can omit the `on` prefix
+fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur');
+```
+
+FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`.
+
+### `fireEvent.press` {#press}
+
+```
+fireEvent.press: (element: ReactTestInstance, ...data: Array) => void
+```
+
+:::note
+It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support.
+:::
+
+Invokes `press` event handler on the element or parent element in the tree.
+
+```jsx
+import { View, Text, TouchableOpacity } from 'react-native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+const onPressMock = jest.fn();
+const eventData = {
+ nativeEvent: {
+ pageX: 20,
+ pageY: 30,
+ },
+};
+
+render(
+
+
+ Press me
+
+ ,
+);
+
+fireEvent.press(screen.getByText('Press me'), eventData);
+expect(onPressMock).toHaveBeenCalledWith(eventData);
+```
+
+### `fireEvent.changeText` {#change-text}
+
+```
+fireEvent.changeText: (element: ReactTestInstance, ...data: Array) => void
+```
+
+:::note
+It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events.
+:::
+
+Invokes `changeText` event handler on the element or parent element in the tree.
+
+```jsx
+import { View, TextInput } from 'react-native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+const onChangeTextMock = jest.fn();
+const CHANGE_TEXT = 'content';
+
+render(
+
+
+ ,
+);
+
+fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT);
+```
+
+### `fireEvent.scroll` {#scroll}
+
+```
+fireEvent.scroll: (element: ReactTestInstance, ...data: Array) => void
+```
+
+Invokes `scroll` event handler on the element or parent element in the tree.
+
+#### On a `ScrollView`
+
+```jsx
+import { ScrollView, Text } from 'react-native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+const onScrollMock = jest.fn();
+const eventData = {
+ nativeEvent: {
+ contentOffset: {
+ y: 200,
+ },
+ },
+};
+
+render(
+
+ XD
+ ,
+);
+
+fireEvent.scroll(screen.getByText('scroll-view'), eventData);
+```
+
+:::note
+
+Prefer using [`user.scrollTo`](./UserEvent.md#scrollto) over `fireEvent.scroll` for `ScrollView`, `FlatList`, and `SectionList` components. User Event provides a more realistic event simulation based on React Native runtime behavior.
+
+:::
+
diff --git a/website/docs/GettingStarted.md b/website/docs/GettingStarted.md
index a12208f7c..6f7c5129f 100644
--- a/website/docs/GettingStarted.md
+++ b/website/docs/GettingStarted.md
@@ -83,24 +83,24 @@ module.exports = {
## Example
```jsx
-import { render, screen, fireEvent } from '@testing-library/react-native';
+import { render, screen, userEvent } from '@testing-library/react-native';
import { QuestionsBoard } from '../QuestionsBoard';
-test('form submits two answers', () => {
- const allQuestions = ['q1', 'q2'];
- const mockFn = jest.fn();
+test('form submits two answers', async () => {
+ const questions = ['q1', 'q2'];
+ const onSubmit = jest.fn();
- render();
+ const user = userEvent.setup();
+ render();
const answerInputs = screen.getAllByLabelText('answer input');
+ await user.type(answerInputs[0], 'a1');
+ await user.type(answerInputs[1], 'a2');
+ await user.press(screen.getByRole('button', { name: 'Submit' }));
- fireEvent.changeText(answerInputs[0], 'a1');
- fireEvent.changeText(answerInputs[1], 'a2');
- fireEvent.press(screen.getByText('Submit'));
-
- expect(mockFn).toBeCalledWith({
- 1: { q: 'q1', a: 'a1' },
- 2: { q: 'q2', a: 'a2' },
+ expect(onSubmit).toHaveBeenCalledWith({
+ '1': { q: 'q1', a: 'a1' },
+ '2': { q: 'q2', a: 'a2' },
});
});
```
diff --git a/website/docs/HowShouldIQuery.md b/website/docs/HowShouldIQuery.md
index 24c137be5..faef9d158 100644
--- a/website/docs/HowShouldIQuery.md
+++ b/website/docs/HowShouldIQuery.md
@@ -21,14 +21,14 @@ For this query, `getBy*` is the query variant, and `*ByRole` is the predicate.
The query variants describe the expected number (and timing) of matching elements, so they differ in their return type.
-| Variant | Assertion | Return type | Is Async? |
-| ----------------------------------------- | ----------------------------- | ------------------------------------------ | --------- |
-| [`getBy*`](api-queries#get-by) | Exactly one matching element | `ReactTestInstance` | No |
-| [`getAllBy*`](api-queries#get-all-by) | At least one matching element | `Array` | No |
-| [`queryBy*`](api-queries#query-by) | Zero or one matching element | ReactTestInstance | null | No |
-| [`queryAllBy*`](api-queries#query-all-by) | No assertion | `Array` | No |
-| [`findBy*`](api-queries#find-by) | Exactly one matching element | `Promise` | Yes |
-| [`findAllBy*`](api-queries#find-all-by) | At least one matching element | `Promise>` | Yes |
+| Variant | Assertion | Return type | Is Async? |
+| ------------------------------------- | ----------------------------- | ------------------------------------------ | --------- |
+| [`getBy*`](queries#get-by) | Exactly one matching element | `ReactTestInstance` | No |
+| [`getAllBy*`](queries#get-all-by) | At least one matching element | `Array` | No |
+| [`queryBy*`](queries#query-by) | Zero or one matching element | ReactTestInstance | null | No |
+| [`queryAllBy*`](queries#query-all-by) | No assertion | `Array` | No |
+| [`findBy*`](queries#find-by) | Exactly one matching element | `Promise` | Yes |
+| [`findAllBy*`](queries#find-all-by) | At least one matching element | `Promise>` | Yes |
Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails.
@@ -49,15 +49,15 @@ Avoid using `queryAllBy*` in regular tests, as it provides no assertions on the
The query predicate describes how you decide whether to match the given element.
-| Predicate | Supported elements | Inspected props |
-| ------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
-| [`*ByRole`](api-queries#by-role) | all host elements | `role`, `accessibilityRole`,
optional: accessible name, accessibility state and value |
-| [`*ByLabelText`](api-queries#by-label-text) | all host elements | `aria-label`, `aria-labelledby`,
`accessibilityLabel`, `accessibilityLabelledBy` |
-| [`*ByDisplayValue`](api-queries#by-display-value) | `TextInput` | `value`, `defaultValue` |
-| [`*ByPlaceholderText`](api-queries#by-placeholder-text) | `TextInput` | `placeholder` |
-| [`*ByText`](api-queries#by-text) | `Text` | `children` (text content) |
-| [`*ByHintText`](api-queries#by-hint-text) | all host elements | `accessibilityHint` |
-| [`*ByTestId`](api-queries#by-test-id) | all host elements | `testID` |
+| Predicate | Supported elements | Inspected props |
+| --------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| [`*ByRole`](queries#by-role) | all host elements | `role`, `accessibilityRole`,
optional: accessible name, accessibility state and value |
+| [`*ByLabelText`](queries#by-label-text) | all host elements | `aria-label`, `aria-labelledby`,
`accessibilityLabel`, `accessibilityLabelledBy` |
+| [`*ByDisplayValue`](queries#by-display-value) | `TextInput` | `value`, `defaultValue` |
+| [`*ByPlaceholderText`](queries#by-placeholder-text) | `TextInput` | `placeholder` |
+| [`*ByText`](queries#by-text) | `Text` | `children` (text content) |
+| [`*ByHintText`](queries#by-hint-text) | all host elements | `accessibilityHint` |
+| [`*ByTestId`](queries#by-test-id) | all host elements | `testID` |
### Idiomatic query predicates
@@ -67,7 +67,7 @@ It is recommended to use query predicates in the following order of priority:
### 1. By Role query {#by-role-query}
-The first and most versatile predicate is [`*ByRole`](api-queries#by-role), which starts with the semantic role of the element and can be further narrowed down with additional options. React Native has two role systems, the web/ARIA-compatible one based on [`role`](https://reactnative.dev/docs/accessibility#role) prop and the traditional one based on [`accessibilityRole`](https://reactnative.dev/docs/accessibility#accessibilityrole) prop, you can use either of these.
+The first and most versatile predicate is [`*ByRole`](queries#by-role), which starts with the semantic role of the element and can be further narrowed down with additional options. React Native has two role systems, the web/ARIA-compatible one based on [`role`](https://reactnative.dev/docs/accessibility#role) prop and the traditional one based on [`accessibilityRole`](https://reactnative.dev/docs/accessibility#accessibilityrole) prop, you can use either of these.
In most cases, you need to set accessibility roles explicitly (or your component library can set some of them for you). These roles allow assistive technologies (like screen readers) and testing code to understand your view hierarchy better.
@@ -91,7 +91,7 @@ Some frequently used roles include:
#### Name option {#by-role-query-name-option}
-Frequently, you will want to add the [`name`](api-queries#by-role-options) option, which will match both the element's role and its accessible name (= element's accessibility label or text content).
+Frequently, you will want to add the [`name`](queries#by-role-options) option, which will match both the element's role and its accessible name (= element's accessibility label or text content).
Here are a couple of examples:
@@ -107,9 +107,9 @@ Querying [`TextInput`](https://reactnative.dev/docs/textinput) elements presents
Therefore, you can use the following queries to find relevant text inputs:
-1. [`*ByLabelText`](api-queries#by-label-text) - will match the accessibility label of the element. This query will match any host elements, including `TextInput` elements.
-2. [`*ByPlaceholderText`](api-queries#by-placeholder-text) - will match the placeholder of `TextInput` element. This query will match only `TextInput` elements.
-3. [`*ByDisplayValue`](api-queries#by-display-value) - will the current (or default) value of `TextInput` element. This query will match only `TextInput` elements.
+1. [`*ByLabelText`](queries#by-label-text) - will match the accessibility label of the element. This query will match any host elements, including `TextInput` elements.
+2. [`*ByPlaceholderText`](queries#by-placeholder-text) - will match the placeholder of `TextInput` element. This query will match only `TextInput` elements.
+3. [`*ByDisplayValue`](queries#by-display-value) - will the current (or default) value of `TextInput` element. This query will match only `TextInput` elements.
### 3. Other accessible queries {#other-accessible-queries}
@@ -117,12 +117,12 @@ These queries reflect the apps' user experience, both visual and through assisti
These queries include:
-- [`*ByText`](api-queries#by-text) - will match the text content of the element. This query will match only `Text` elements.
-- [`*ByLabelText`](api-queries#by-label-text) - will match the accessibility label of the element.
-- [`*ByHintText`](api-queries#by-hint-text) - will match the accessibility hint of the element.
+- [`*ByText`](queries#by-text) - will match the text content of the element. This query will match only `Text` elements.
+- [`*ByLabelText`](queries#by-label-text) - will match the accessibility label of the element.
+- [`*ByHintText`](queries#by-hint-text) - will match the accessibility hint of the element.
### 4. Test ID query {#test-id-query}
-As a final predicate, you can use the `testID` prop to find relevant views. Using the [`*ByTestId`](api-queries#by-test-id) predicate offers the most flexibility, but at the same time, it does not represent the user experience, as users are not aware of test IDs.
+As a final predicate, you can use the `testID` prop to find relevant views. Using the [`*ByTestId`](queries#by-test-id) predicate offers the most flexibility, but at the same time, it does not represent the user experience, as users are not aware of test IDs.
Note that using test IDs is a widespread technique in end-to-end testing due to various issues with querying views through other means **in its specific context**. Nevertheless, we still encourage you to use recommended RNTL queries as it will make your integration and component test more reliable and resilient.
diff --git a/website/docs/MigrationV12.md b/website/docs/MigrationV12.md
index d53d5014a..1684fabdf 100644
--- a/website/docs/MigrationV12.md
+++ b/website/docs/MigrationV12.md
@@ -24,7 +24,7 @@ React Native Testing Library 12 introduces a handful of breaking changes compare
Elements that are hidden from accessiblity, e.g. elements on non-active screen when using React Navigation, now will not be matched by default by all queries. This is the effect of switching the default value for global config option `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) to `false`.
-Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](api-queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option.
+Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option.
### 2. `*ByRole` queries now return only accessibility elements
@@ -69,7 +69,7 @@ Problematic cases may include: directly checking some prop values (without using
### 4. `container` API has been renamed to `UNSAFE_root`.
-Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/api/#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance.
+Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/screen#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance.
RNTL v12 introduces `root` API as an alternative that returns a root **host** element. The difference between `root` and `UNSAFE_root` properties is that that `root` will always represents a host element, while `UNSAFE_root` will typically represent a composite element.
diff --git a/website/docs/MigrationV7.md b/website/docs/MigrationV7.md
index b426a10b5..46bcc7f6f 100644
--- a/website/docs/MigrationV7.md
+++ b/website/docs/MigrationV7.md
@@ -117,4 +117,4 @@ There are slight differences in how `fireEvent` works in both libraries:
+fireEvent(element: ReactTestInstance, eventName: string, ...data: Array)
```
1. There is no `NativeTestEvent` - second and rest arguments are used instead.
-1. There are only 3 short-hand events: [`fireEvent.press`](api/#fireeventpress-element-reacttestinstance--void), [`fireEvent.changeText`](api/#fireeventchangetext-element-reacttestinstance-data-arrayany--void) and [`fireEvent.scroll`](api/#fireeventscroll-element-reacttestinstance-data-arrayany--void). For all other or custom events you can use the base signature.
+1. There are only 3 short-hand events: [`fireEvent.press`](fire-event#press), [`fireEvent.changeText`](fire-event#change-text) and [`fireEvent.scroll`](fire-event#scroll). For all other or custom events you can use the base signature.
diff --git a/website/docs/MigrationV9.md b/website/docs/MigrationV9.md
index 46b7923b8..5e745f84f 100644
--- a/website/docs/MigrationV9.md
+++ b/website/docs/MigrationV9.md
@@ -13,7 +13,7 @@ Version 7.0 brought React Native Testing Library into the `@testing-library` fam
This is a backward compatible change.
-When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case:
+When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case:
```jsx
const { getByText } = render(Hello World);
diff --git a/website/docs/OtherAPIs.md b/website/docs/OtherAPIs.md
new file mode 100644
index 000000000..0db8d2595
--- /dev/null
+++ b/website/docs/OtherAPIs.md
@@ -0,0 +1,301 @@
+---
+id: other
+title: Other APIs
+---
+
+## Async utilities
+
+### `findBy*` queries
+
+The `findBy*` queries are used to find elements that are not instantly available but will be added as a result of some asynchronous action. Learn more details [here](queries#find-by).
+
+### `waitFor`
+
+```tsx
+function waitFor(
+ expectation: () => T,
+ { timeout: number = 1000, interval: number = 50 },
+): Promise {}
+```
+
+Waits for a period of time for the `expectation` callback to pass. `waitFor` may run the callback a number of times until timeout is reached, as specified by the `timeout` and `interval` options. The callback must throw an error when the expectation is not met. Returning any value, including a falsy one, will be treated as meeting the expectation, and the callback result will be returned to the caller of `waitFor` function.
+
+```tsx
+await waitFor(() => expect(mockFunction).toHaveBeenCalledWith());
+```
+
+`waitFor` function will be executing `expectation` callback every `interval` (default: every 50 ms) until `timeout` (default: 1000 ms) is reached. The repeated execution of callback is stopped as soon as it does not throw an error, in such case the value returned by the callback is returned to `waitFor` caller. Otherwise, when it reaches the timeout, the final error thrown by `expectation` will be re-thrown by `waitFor` to the calling code.
+
+```tsx
+// ❌ `waitFor` will return immediately because callback does not throw
+await waitFor(() => false);
+```
+
+`waitFor` is an async function so you need to `await` the result to pause test execution.
+
+```jsx
+// ❌ missing `await`: `waitFor` will just return Promise that will be rejected when the timeout is reached
+waitFor(() => expect(1).toBe(2));
+```
+
+:::note
+You can enforce awaiting `waitFor` by using the [await-async-utils](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/await-async-utils.md) rule from [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library).
+:::
+
+Since `waitFor` is likely to run `expectation` callback multiple times, it is highly recommended for it [not to perform any side effects](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#performing-side-effects-in-waitfor) in `waitFor`.
+
+```jsx
+await waitFor(() => {
+ // ❌ button will be pressed on each waitFor iteration
+ fireEvent.press(screen.getByText('press me'));
+ expect(mockOnPress).toHaveBeenCalled();
+});
+```
+
+:::note
+Avoiding side effects in `expectation` callback can be partially enforced with the [`no-wait-for-side-effects` rule](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-side-effects.md).
+:::
+
+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
+let fakeTimeRemaining = timeout;
+let lastError;
+
+while (fakeTimeRemaining > 0) {
+ fakeTimeRemaining = fakeTimeRemaining - interval;
+ jest.advanceTimersByTime(interval);
+ try {
+ // resolve
+ return expectation();
+ } catch (error) {
+ lastError = error;
+ }
+}
+
+// reject
+throw lastError;
+```
+
+In the following example we test that a function is called after 10 seconds using fake timers. Since we're using fake timers, the test won't depend on real time passing and thus be much faster and more reliable. Also we don't have to advance fake timers through Jest fake timers API because `waitFor` already does this for us.
+
+```tsx
+// in component
+setTimeout(() => {
+ someFunction();
+}, 10000);
+
+// in test
+jest.useFakeTimers();
+
+await waitFor(() => {
+ expect(someFunction).toHaveBeenCalledWith();
+}, 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](./UnderstandingAct.md) function document.
+:::
+
+### `waitForElementToBeRemoved`
+
+```ts
+function waitForElementToBeRemoved(
+ expectation: () => T,
+ { timeout: number = 4500, interval: number = 50 },
+): Promise {}
+```
+
+Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not.
+
+```jsx
+import { render, screen, waitForElementToBeRemoved } from '@testing-library/react-native';
+
+test('waiting for an Banana to be removed', async () => {
+ render();
+
+ await waitForElementToBeRemoved(() => screen.getByText('Banana ready'));
+});
+```
+
+This method expects that the element is initially present in the render tree and then is removed from it. If the element is not present when you call this method it throws an error.
+
+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](./UnderstandingAct.md) function document.
+:::
+
+## Configuration
+
+### `configure`
+
+```ts
+type Config = {
+ asyncUtilTimeout: number;
+ defaultHidden: boolean;
+ defaultDebugOptions: Partial;
+};
+
+function configure(options: Partial) {}
+```
+
+#### `asyncUtilTimeout` option
+
+Default timeout, in ms, for async helper functions (`waitFor`, `waitForElementToBeRemoved`) and `findBy*` queries. Defaults to 1000 ms.
+
+#### `defaultIncludeHiddenElements` option
+
+Default value for [includeHiddenElements](Queries.md#includehiddenelements-option) query option for all queries. The default value is set to `false`, so all queries will not match [elements hidden from accessibility](#ishiddenfromaccessibility). This is because the users of the app would not be able to see such elements.
+
+This option is also available as `defaultHidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden).
+
+#### `defaultDebugOptions` option
+
+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()`.
+
+### `resetToDefaults()`
+
+```ts
+function resetToDefaults() {}
+```
+
+### Environment variables
+
+#### `RNTL_SKIP_AUTO_CLEANUP`
+
+Set to `true` to disable automatic `cleanup()` after each test. It works the same as importing `react-native-testing-library/dont-cleanup-after-each` or using `react-native-testing-library/pure`.
+
+```shell
+$ RNTL_SKIP_AUTO_CLEANUP=true jest
+```
+
+#### `RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS`
+
+Set to `true` to disable auto-detection of fake timers. This might be useful in rare cases when you want to use non-Jest fake timers. See [issue #886](https://github.com/callstack/react-native-testing-library/issues/886) for more details.
+
+```shell
+$ RNTL_SKIP_AUTO_DETECT_FAKE_TIMERS=true jest
+```
+
+## Accessibility
+
+### `isHiddenFromAccessibility`
+
+```ts
+function isHiddenFromAccessibility(
+ element: ReactTestInstance | null
+): boolean {}
+```
+
+Also available as `isInaccessible()` alias for React Testing Library compatibility.
+
+Checks if given element is hidden from assistive technology, e.g. screen readers.
+
+:::note
+Like [`isInaccessible`](https://testing-library.com/docs/dom-testing-library/api-accessibility/#isinaccessible) function from DOM Testing Library this function considers both accessibility elements and presentational elements (regular `View`s) to be accessible, unless they are hidden in terms of host platform.
+
+This covers only part of [ARIA notion of Accessiblity Tree](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), as ARIA excludes both hidden and presentational elements from the Accessibility Tree.
+:::
+
+For the scope of this function, element is inaccessible when it, or any of its ancestors, meets any of the following conditions:
+
+- it has `display: none` style
+- it has [`aria-hidden`](https://reactnative.dev/docs/accessibility#aria-hidden) prop set to `true`
+- it has [`accessibilityElementsHidden`](https://reactnative.dev/docs/accessibility#accessibilityelementshidden-ios) prop set to `true`
+- it has [`importantForAccessibility`](https://reactnative.dev/docs/accessibility#importantforaccessibility-android) prop set to `no-hide-descendants`
+- it has sibling host element with either [`aria-modal`](https://reactnative.dev/docs/accessibility#aria-modal-ios) or [`accessibilityViewIsModal`](https://reactnative.dev/docs/accessibility#accessibilityviewismodal-ios) prop set to `true`
+
+Specifying `accessible={false}`, `accessiblityRole="none"`, or `importantForAccessibility="no"` props does not cause the element to become inaccessible.
+
+## Other helpers
+
+### `within`, `getQueriesForElement`
+
+```jsx
+function within(element: ReactTestInstance): Queries {}
+
+function getQueriesForElement(element: ReactTestInstance): Queries {}
+```
+
+`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element.
+
+:::note
+Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included.
+:::
+
+```jsx
+const detailsScreen = within(screen.getByA11yHint('Details Screen'));
+expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen();
+expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen();
+expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen();
+await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen();
+```
+
+Use cases for scoped queries include:
+
+- queries scoped to a single item inside a FlatList containing many items
+- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation)
+
+### `act`
+
+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](./UnderstandingAct.md) document for more understanding of its intricacies.
+
+### `cleanup`
+
+```ts
+const cleanup: () => void;
+```
+
+Unmounts React trees that were mounted with `render` and clears `screen` variable that holds latest `render` output.
+
+:::info
+Please note that this is done automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test.
+:::
+
+For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so:
+
+```jsx
+import { cleanup, render } from '@testing-library/react-native/pure';
+import { View } from 'react-native';
+
+afterEach(cleanup);
+
+it('renders a view', () => {
+ render();
+ // ...
+});
+```
+
+The `afterEach(cleanup)` call also works in `describe` blocks:
+
+```jsx
+describe('when logged in', () => {
+ afterEach(cleanup);
+
+ it('renders the user', () => {
+ render();
+ // ...
+ });
+});
+```
+
+Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).
\ No newline at end of file
diff --git a/website/docs/Queries.md b/website/docs/Queries.md
index 867db47e8..e73f021b2 100644
--- a/website/docs/Queries.md
+++ b/website/docs/Queries.md
@@ -1,6 +1,6 @@
---
-id: api-queries
-title: Queries
+id: queries
+title: Queries API
---
Queries are one of the main building blocks for the React Native Testing Library. They enable you to find relevant elements in the element tree, which represents the your application's user interface when running under tests.
@@ -52,14 +52,14 @@ For this query, `getBy*` is the query variant, and `*ByRole` is the predicate.
The query variants describe the expected number (and timing) of matching elements, so they differ in their return type.
-| Variant | Assertion | Return type | Is Async? |
-| ----------------------------------------- | ----------------------------- | ------------------------------------------ | --------- |
-| [`getBy*`](api-queries#get-by) | Exactly one matching element | `ReactTestInstance` | No |
-| [`getAllBy*`](api-queries#get-all-by) | At least one matching element | `Array` | No |
-| [`queryBy*`](api-queries#query-by) | Zero or one matching element | ReactTestInstance | null | No |
-| [`queryAllBy*`](api-queries#query-all-by) | No assertion | `Array` | No |
-| [`findBy*`](api-queries#find-by) | Exactly one matching element | `Promise` | Yes |
-| [`findAllBy*`](api-queries#find-all-by) | At least one matching element | `Promise>` | Yes |
+| Variant | Assertion | Return type | Is Async? |
+| ------------------------------------- | ----------------------------- | ------------------------------------------ | --------- |
+| [`getBy*`](queries#get-by) | Exactly one matching element | `ReactTestInstance` | No |
+| [`getAllBy*`](queries#get-all-by) | At least one matching element | `Array` | No |
+| [`queryBy*`](queries#query-by) | Zero or one matching element | ReactTestInstance | null | No |
+| [`queryAllBy*`](queries#query-all-by) | No assertion | `Array` | No |
+| [`findBy*`](queries#find-by) | Exactly one matching element | `Promise` | Yes |
+| [`findAllBy*`](queries#find-all-by) | At least one matching element | `Promise>` | Yes |
Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails.
@@ -124,7 +124,7 @@ findAllByX(
`findAllBy*` queries return a promise which resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms.
:::info
-`findBy*` and `findAllBy*` queries accept optional `waitForOptions` object arguments, which can contain `timeout`, `interval` and `onTimeout` properties which have the same meaning as respective options for [`waitFor`](api#waitfor) function.
+`findBy*` and `findAllBy*` queries accept optional `waitForOptions` object arguments, which can contain `timeout`, `interval` and `onTimeout` properties which have the same meaning as respective options for [`waitFor`](other#waitfor) function.
:::
:::info
@@ -501,9 +501,9 @@ Usually query first argument can be a **string** or a **regex**. All queries tak
#### `includeHiddenElements` option
-All queries have the `includeHiddenElements` option which affects whether [elements hidden from accessibility](./API.md#ishiddenfromaccessibility) are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements.
+All queries have the `includeHiddenElements` option which affects whether [elements hidden from accessibility](other#ishiddenfromaccessibility) are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements.
-You can configure the default value with the [`configure` function](API.md#configure).
+You can configure the default value with the [`configure` function](other#configure).
This option is also available as `hidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/queries/byrole#hidden).
diff --git a/website/docs/Render.md b/website/docs/Render.md
new file mode 100644
index 000000000..6298c2ee9
--- /dev/null
+++ b/website/docs/Render.md
@@ -0,0 +1,64 @@
+---
+id: render
+title: Render API
+---
+
+```jsx
+function render(
+ component: React.Element,
+ options?: RenderOptions
+): RenderResult
+```
+
+The `render` function is the entry point for writing React Native Testing Library tests. It deeply renders the given React element and returns helpers to query the output components' structure.
+
+```jsx
+import { render } from '@testing-library/react-native';
+
+test('basic test', () => {
+ render();
+ expect(screen.getAllByRole('button', { name: 'start' })).toBeOnTheScreen();
+});
+```
+
+> When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases, it's convenient to create your own custom `render` method. [Follow this great guide on how to set this up](https://testing-library.com/docs/react-testing-library/setup#custom-render).
+
+### Options {#render-options}
+
+The behavior of the `render` method can be customized by passing various options as a second argument of the `RenderOptions` type:
+
+#### `wrapper` option
+
+```ts
+wrapper?: React.ComponentType,
+```
+
+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.
+
+#### `createNodeMock` option
+
+```ts
+createNodeMock?: (element: React.Element) => any,
+```
+
+This option allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this option from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas).
+
+#### `unstable_validateStringsRenderedWithinText` option
+
+```ts
+unstable_validateStringsRenderedWithinText?: boolean;
+```
+
+:::note
+This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes.
+:::
+
+This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g., under ``.
+
+React Test Renderer does not enforce this check; hence, by default, React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests.
+
+### Result {#render-result}
+
+The `render` function returns the same queries and utilities as the [`screen`](screen) object. We recommended using the `screen` object as more developer-friendly way.
+
+See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details.
diff --git a/website/docs/RenderHook.md b/website/docs/RenderHook.md
new file mode 100644
index 000000000..54c828f00
--- /dev/null
+++ b/website/docs/RenderHook.md
@@ -0,0 +1,131 @@
+---
+id: render-hook
+title: Render Hook API
+---
+
+```ts
+function renderHook(
+ callback: (props?: Props) => Result,
+ options?: RenderHookOptions,
+): RenderHookResult;
+```
+
+Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders. Returns [`RenderHookResult`](#renderhookresult) object, which you can interact with.
+
+```ts
+import { renderHook } from '@testing-library/react-native';
+import { useCount } from '../useCount';
+
+it('should increment count', () => {
+ const { result } = renderHook(() => useCount());
+
+ expect(result.current.count).toBe(0);
+ act(() => {
+ // Note that you should wrap the calls to functions your hook returns with `act` if they trigger an update of your hook's state to ensure pending useEffects are run before your next assertion.
+ result.current.increment();
+ });
+ expect(result.current.count).toBe(1);
+});
+```
+
+```ts
+// useCount.js
+export const useCount = () => {
+ const [count, setCount] = useState(0);
+ const increment = () => setCount((previousCount) => previousCount + 1);
+
+ return { count, increment };
+};
+```
+
+The `renderHook` function accepts the following arguments:
+
+Callback is a function that is called each `render` of the test component. This function should call one or more hooks for testing.
+
+The `props` passed into the callback will be the `initialProps` provided in the `options` to `renderHook`, unless new props are provided by a subsequent `rerender` call.
+
+## `options`
+
+A `RenderHookOptions` object to modify the execution of the `callback` function, containing the following properties:
+
+### `initialProps`
+
+The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
+
+### `wrapper`
+
+A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`.
+
+## `RenderHookResult`
+
+```ts
+interface RenderHookResult {
+ result: { current: Result };
+ rerender: (props: Props) => void;
+ unmount: () => void;
+}
+```
+
+The `renderHook` function returns an object that has the following properties:
+
+### `result`
+
+The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call.
+
+### `rerender`
+
+A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
+
+### `unmount`
+
+A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks.
+
+## Examples
+
+Here we present some extra examples of using `renderHook` API.
+
+### With `initialProps`
+
+```ts
+const useCount = (initialCount: number) => {
+ const [count, setCount] = useState(initialCount);
+ const increment = () => setCount((previousCount) => previousCount + 1);
+
+ useEffect(() => {
+ setCount(initialCount);
+ }, [initialCount]);
+
+ return { count, increment };
+};
+
+it('should increment count', () => {
+ const { result, rerender } = renderHook((initialCount: number) => useCount(initialCount), {
+ initialProps: 1,
+ });
+
+ expect(result.current.count).toBe(1);
+
+ act(() => {
+ result.current.increment();
+ });
+
+ expect(result.current.count).toBe(2);
+ rerender(5);
+ expect(result.current.count).toBe(5);
+});
+```
+
+### With `wrapper`
+
+```tsx
+it('should use context value', () => {
+ function Wrapper({ children }: { children: ReactNode }) {
+ return {children};
+ }
+
+ const { result } = renderHook(() => useHook(), { wrapper: Wrapper });
+ // ...
+});
+```
+
+
diff --git a/website/docs/Screen.md b/website/docs/Screen.md
new file mode 100644
index 000000000..540362f7c
--- /dev/null
+++ b/website/docs/Screen.md
@@ -0,0 +1,157 @@
+---
+id: screen
+title: Screen API
+---
+
+```ts
+let screen: {
+ ...queries;
+ rerender(element: React.Element): void;
+ unmount(): void;
+ debug(options?: DebugOptions): void
+ toJSON(): ReactTestRendererJSON | null;
+ root: ReactTestInstance;
+ UNSAFE_root: ReactTestInstance;
+};
+```
+
+The `screen` object offers a recommended way to access queries and utilities for the currently rendered UI.
+
+This object is assigned after the `render` call and cleared after each test by calling [`cleanup`](other#cleanup). If no `render` call has been made in a given test, then it holds a special object and throws a helpful error on each property and method access.
+
+### `...queries`
+
+The most important feature of `screen` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy.
+
+See [Queries](./Queries.md) for a complete list.
+
+#### Example
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+render();
+const buttonStart = screen.getByRole('button', { name: 'start' })
+```
+
+### `rerender`
+
+_Also available under `update` alias_
+
+```ts
+function rerender(element: React.Element): void
+```
+
+Re-render the in-memory tree with a new root element. This simulates a React update render at the root. If the new element has the same type (and `key`) as the previous element, the tree will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events.
+
+### `unmount`
+
+```ts
+function unmount(): void
+```
+
+Unmount the in-memory tree, triggering the appropriate lifecycle events.
+
+:::note
+Usually you should not need to call `unmount` as it is done automatically if your test runner supports `afterEach` hook (like Jest, mocha, Jasmine).
+:::
+
+### `debug`
+
+```ts
+function debug(options?: {
+ message?: string;
+ mapProps?: MapPropsFunction;
+}): void
+```
+
+Pretty prints deeply rendered component passed to `render`.
+
+#### `message` option {#debug-message-option}
+
+You can provide a message that will be printed on top.
+
+```jsx
+render();
+screen.debug({ message: 'optional message' });
+```
+
+logs optional message and colored JSX:
+
+```jsx
+optional message
+
+
+ Press me
+
+```
+
+#### `mapProps` option {#debug-map-props-option}
+
+```ts
+function debug({ mapProps: (props) => ({}) });
+```
+
+You can use the `mapProps` option to transform the props that will be printed :
+
+```jsx
+render();
+screen.debug({ mapProps: ({ style, ...props }) => ({ props }) });
+```
+
+This will log the rendered JSX without the `style` props.
+
+The `children` prop cannot be filtered out so the following will print all rendered components with all props but `children` filtered out.
+
+This option can be used to target specific props when debugging a query (for instance, keeping only the `children` prop when debugging a `getByText` query).
+
+You can also transform prop values so that they are more readable (e.g., flatten styles).
+
+```ts
+import { StyleSheet } from 'react-native';
+
+screen.debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) });
+```
+
+Or remove props that have little value when debugging tests, e.g. path prop for svgs
+
+```ts
+screen.debug({ mapProps: ({ path, ...props }) => ({ ...props }) });
+```
+
+### `toJSON`
+
+```ts
+function toJSON(): ReactTestRendererJSON | null
+```
+
+Get the rendered component JSON representation, e.g. for snapshot testing.
+
+### `root`
+
+```ts
+const root: ReactTestInstance;
+```
+
+Returns the rendered root [host element](testing-env#host-and-composite-components).
+
+This API is primarily useful for component tests, as it allows you to access root host view without using `*ByTestId` queries or similar methods.
+
+### `UNSAFE_root`
+
+:::caution
+This API typically will return a composite view, which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing.
+:::
+
+```ts
+const UNSAFE_root: ReactTestInstance;
+```
+
+Returns the rendered [composite root element](testing-env#host-and-composite-components).
+
+:::note
+This API has been previously named `container` for compatibility with [React Testing Library](https://testing-library.com/docs/react-testing-library/other#container-1). However, despite the same name, the actual behavior has been significantly different; hence, we decided to change the name to `UNSAFE_root`.
+:::
+
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index a7e8b60fd..271ea13d7 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -42,7 +42,7 @@ const siteConfig = {
{
key: 2,
label: 'API',
- to: 'docs/api',
+ to: 'docs/render',
},
],
},
diff --git a/website/sidebars.js b/website/sidebars.js
index 98c352a8e..31c74c70c 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -1,7 +1,16 @@
module.exports = {
docs: {
Introduction: ['getting-started'],
- 'API Reference': ['api', 'api-queries', 'user-event', 'jest-matchers'],
+ 'API Reference': [
+ 'render',
+ 'screen',
+ 'queries',
+ 'user-event',
+ 'fire-event',
+ 'jest-matchers',
+ 'render-hook',
+ 'other',
+ ],
Guides: ['how-should-i-query', 'troubleshooting', 'faq'],
Advanced: ['testing-env', 'understanding-act'],
Community: ['community-resources'],