async events

Author: mdjastrzebski

website/docs/14.x/cookbook/advanced/network-requests.md

@@ -246,7 +246,7 @@ afterAll(() => server.close());
 
 describe('PhoneBook', () => {
   it('fetches all contacts and favorites successfully and renders lists in sections correctly', async () => {
-    render(<PhoneBook />);
+    await render(<PhoneBook />);
 
     await waitForElementToBeRemoved(() => screen.getByText(/users data not quite there yet/i));
     expect(await screen.findByText('Name: Mrs Ida Kristensen')).toBeOnTheScreen();
@@ -325,7 +325,7 @@ describe('PhoneBook', () => {
 ...
   it('fails to fetch all contacts and renders error message', async () => {
     mockServerFailureForGetAllContacts();
-    render(<PhoneBook />);
+    await render(<PhoneBook />);
 
     await waitForElementToBeRemoved(() => screen.getByText(/users data not quite there yet/i));
     expect(

website/docs/14.x/cookbook/basics/_meta.json

@@ -1 +1 @@
-["async-tests", "custom-render"]
+["async-events", "custom-render"]

…docs/14.x/cookbook/basics/async-tests.md …ocs/14.x/cookbook/basics/async-events.mdwebsite/docs/14.x/cookbook/basics/async-tests.md renamed to website/docs/14.x/cookbook/basics/async-events.md website/docs/14.x/cookbook/basics/async-tests.md renamed to website/docs/14.x/cookbook/basics/async-events.md

@@ -1,17 +1,18 @@
-# Async tests
+# Async Events
 
 ## Summary
 
-Typically, you would write synchronous tests, as they are simple and get the work done. However, there are cases when using asynchronous (async) tests might be necessary or beneficial. The two most common cases are:
+In RNTL v14, all tests are async since `render()`, `fireEvent()`, and other core APIs return Promises. Beyond the basic async APIs, there are additional async utilities for handling events that complete over time:
 
-1. **Testing Code with asynchronous operations**: When your code relies on asynchronous operations, such as network calls or database queries, async tests are essential. Even though you should mock these network calls, the mock should act similarly to the actual behavior and hence by async.
-2. **UserEvent API:** Using the [User Event API](docs/api/events/user-event) in your tests creates more realistic event handling. These interactions introduce delays (even though these are typically event-loop ticks with 0 ms delays), requiring async tests to handle the timing correctly.
+1. **Waiting for elements to appear**: Use `findBy*` queries when elements appear after some delay (e.g., after data fetching).
+2. **Waiting for conditions**: Use `waitFor()` to wait for arbitrary conditions to be met.
+3. **Waiting for elements to disappear**: Use `waitForElementToBeRemoved()` when elements should be removed after some action.
 
-Using async tests when needed ensures your tests are reliable and simulate real-world conditions accurately.
+These utilities help you write reliable tests that properly handle timing in your application.
 
 ### Example
 
-Consider a basic asynchronous test for a user signing in with correct credentials:
+Consider a test for a user signing in with correct credentials:
 
 ```javascript
 test('User can sign in with correct credentials', async () => {

website/docs/14.x/cookbook/basics/custom-render.md

@@ -16,12 +16,12 @@ interface RenderWithProvidersProps {
 
 export async function renderWithProviders<T>(
   ui: React.ReactElement<T>,
-  options?: RenderWithProvidersProps
+  options?: RenderWithProvidersProps,
 ) {
   return await render(
     <UserProvider.Provider value={options?.user ?? null}>
       <ThemeProvider.Provider value={options?.theme ?? 'light'}>{ui}</ThemeProvider.Provider>
-    </UserProvider.Provider>
+    </UserProvider.Provider>,
   );
 }
 ```
@@ -51,8 +51,8 @@ Example [full source code](https://github.com/callstack/react-native-testing-lib
 A custom render function might accept additional parameters to allow for setting up different start conditions for a test, e.g., the initial state for global state management.
 
 ```tsx title=SomeScreen.test.tsx
-test('renders SomeScreen for logged in user', () => {
-  renderScreen(<SomeScreen />, { state: loggedInState });
+test('renders SomeScreen for logged in user', async () => {
+  await renderScreen(<SomeScreen />, { state: loggedInState });
   // ...
 });
 ```
@@ -66,13 +66,18 @@ function renderNavigator(ui, options);
 function renderScreen(ui, options);
 ```
 
-#### Async function
+#### Async setup
 
-Make it async if you want to put some async setup in your custom render function.
+Since `render` is async, your custom render function should be marked as `async` and use `await render()`. This pattern also makes it easy to add additional async setup if needed:
 
 ```tsx title=SomeScreen.test.tsx
+async function renderWithData<T>(ui: React.ReactElement<T>) {
+  const data = await fetchTestData();
+  return await render(<DataProvider value={data}>{ui}</DataProvider>);
+}
+
 test('renders SomeScreen', async () => {
-  await renderWithAsync(<SomeScreen />);
+  await renderWithData(<SomeScreen />);
   // ...
 });
 ```

website/docs/14.x/cookbook/state-management/jotai.md

@@ -65,18 +65,18 @@ We can test our `TaskList` component using React Native Testing Library's (RNTL)
 function. Although it is sufficient to test the empty state of the `TaskList` component, it is not
 enough to test the component with initial tasks present in the list.
 
-```tsx title=status-management/jotai/__tests__/TaskList.test.tsx
+```tsx title=state-management/jotai/__tests__/TaskList.test.tsx
 import * as React from 'react';
 import { render, screen, userEvent } from '@testing-library/react-native';
 import { renderWithAtoms } from './test-utils';
-import { TaskList } from './TaskList';
-import { newTaskTitleAtom, tasksAtom } from './state';
-import { Task } from './types';
+import { TaskList } from '../TaskList';
+import { newTaskTitleAtom, tasksAtom } from '../state';
+import { Task } from '../types';
 
 jest.useFakeTimers();
 
-test('renders an empty task list', () => {
-  render(<TaskList />);
+test('renders an empty task list', async () => {
+  await render(<TaskList />);
   expect(screen.getByText(/no tasks, start by adding one/i)).toBeOnTheScreen();
 });
 ```
@@ -88,7 +88,7 @@ initial values. We can create a custom render function that uses Jotai's `useHyd
 hydrate the atoms with initial values. This function will accept the initial atoms and their
 corresponding values as an argument.
 
-```tsx title=status-management/jotai/test-utils.tsx
+```tsx title=state-management/jotai/__tests__/test-utils.tsx
 import * as React from 'react';
 import { render } from '@testing-library/react-native';
 import { useHydrateAtoms } from 'jotai/utils';
@@ -108,14 +108,14 @@ export interface RenderWithAtomsOptions {
  * @param options - The render options including the initial atom values.
  * @returns The render result from `@testing-library/react-native`.
  */
-export const renderWithAtoms = <T,>(
+export async function renderWithAtoms<T>(
   component: React.ReactElement,
-  options: RenderWithAtomsOptions
-) => {
-  return render(
-    <HydrateAtomsWrapper initialValues={options.initialValues}>{component}</HydrateAtomsWrapper>
+  options: RenderWithAtomsOptions,
+) {
+  return await render(
+    <HydrateAtomsWrapper initialValues={options.initialValues}>{component}</HydrateAtomsWrapper>,
   );
-};
+}
 
 export type HydrateAtomsWrapperProps = React.PropsWithChildren<{
   initialValues: AtomInitialValueTuple<unknown>[];
@@ -144,12 +144,11 @@ We can now use the `renderWithAtoms` function to render the `TaskList` component
 In our test, we populated only one atom and its initial value, but you can add other Jotai atoms and their corresponding values to the initialValues array as needed.
 :::
 
-```tsx title=status-management/jotai/__tests__/TaskList.test.tsx
-=======
+```tsx title=state-management/jotai/__tests__/TaskList.test.tsx
 const INITIAL_TASKS: Task[] = [{ id: '1', title: 'Buy bread' }];
 
 test('renders a to do list with 1 items initially, and adds a new item', async () => {
-  renderWithAtoms(<TaskList />, {
+  await renderWithAtoms(<TaskList />, {
     initialValues: [
       [tasksAtom, INITIAL_TASKS],
       [newTaskTitleAtom, ''],
@@ -202,7 +201,7 @@ No special setup is required to test these functions, as `store.set` is availabl
 Jotai.
 
 ```tsx title=state-management/jotai/__tests__/TaskList.test.tsx
-import { addTask, getAllTasks, store, tasksAtom } from './state';
+import { addTask, getAllTasks, store, tasksAtom } from '../state';
 
 //...
 

website/docs/14.x/docs/start/intro.md

@@ -6,7 +6,7 @@ You want to write maintainable tests for your React Native components. As a part
 
 ## This solution
 
-The React Native Testing Library (RNTL) is a lightweight solution for testing React Native components. It provides light utility functions on top of [Test Renderer](https://github.com/mdjastrzebski/test-renderer), in a way that encourages better testing practices. Its primary guiding principle is:
+The React Native Testing Library (RNTL) is a comprehensive solution for testing React Native components. It provides React Native runtime simulation on top of [Test Renderer](https://github.com/mdjastrzebski/test-renderer), in a way that encourages better testing practices. Its primary guiding principle is:
 
 > The more your tests resemble how your software is used, the more confidence they can give you.
 
@@ -23,7 +23,7 @@ test('form submits two answers', async () => {
   const onSubmit = jest.fn();
 
   const user = userEvent.setup();
-  render(<QuestionsBoard questions={questions} onSubmit={onSubmit} />);
+  await render(<QuestionsBoard questions={questions} onSubmit={onSubmit} />);
 
   const answerInputs = screen.getAllByLabelText('answer input');
   await user.type(answerInputs[0], 'a1');

website/docs/14.x/docs/start/quick-start.mdx

@@ -13,7 +13,16 @@ Open a Terminal in your project's folder and run:
   }}
 />
 
-This library uses [Test Renderer](https://github.com/mdjastrzebski/test-renderer) as its underlying renderer. Test Renderer is automatically installed as a dependency and provides better compatibility with React 19 and improved type safety compared to the deprecated [React Test Renderer](https://reactjs.org/docs/test-renderer.html).
+This library has a peer dependency on [Test Renderer](https://github.com/mdjastrzebski/test-renderer). Make sure to install it:
+
+<PackageManagerTabs
+  command={{
+    yarn: 'yarn add -D test-renderer',
+    npm: 'npm install -D test-renderer',
+  }}
+/>
+
+Test Renderer provides better compatibility with React 19 and improved type safety compared to the deprecated [React Test Renderer](https://reactjs.org/docs/test-renderer.html).
 
 ### Jest matchers