@testing-library/react-native 14.0.0-rc.0 → 14.0.0-rc.1

package/docs/api/render.md

@@ -0,0 +1,49 @@
+# `render` API
+
+## `render` function
+
+```ts
+async function render<T>(
+  element: React.ReactElement<T>,
+  options?: RenderOptions,
+): Promise<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. The function is async and uses async `act` internally, so all pending React updates run before it resolves. This works with async React features like `Suspense` boundaries and the `use()` hook.
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+test('basic test', async () => {
+  await render(<MyApp />);
+  expect(screen.getAllByRole('button', { name: 'start' })).toBeOnTheScreen();
+});
+```
+
+> When using React context providers like Redux Provider, you'll likely want to wrap the rendered component with them. In such cases, create your own custom `render` method. [Follow this guide on how to set it up](https://testing-library.com/docs/react-testing-library/setup#custom-render).
+
+### Options
+
+You can customize the `render` method by passing options as the second argument:
+
+#### `wrapper`
+
+```ts
+wrapper?: React.ComponentType<any>,
+```
+
+Wraps the tested component in an additional wrapper component. Use this to create custom render functions for common React Context providers.
+
+> [!NOTE] Text string validation
+> Test Renderer enforces React Native's requirement that text strings must be rendered within a `<Text>` component. If you render a `string` value under components other than `<Text>` (e.g., under `<View>`), it throws an `Invariant Violation: Text strings must be rendered within a <Text> component` error. This matches React Native's runtime behavior.
+>
+> This validation is always enabled and cannot be disabled. Your tests will catch the same text rendering errors that would occur in production.
+
+### Result
+
+The `render` function returns a promise that resolves to the same queries and utilities as the [`screen`](./screen.md) object. Use `screen` for queries and the lifecycle methods from the render result when needed.
+
+See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details.
+
+> [!NOTE] Type information
+> Query results and element references use the `TestInstance` type from [Test Renderer](https://github.com/mdjastrzebski/test-renderer). If you need to type element variables, import this type directly from `test-renderer`.

package/docs/api/screen.md

@@ -0,0 +1,188 @@
+# `screen` object
+
+```ts
+let screen: {
+  ...queries;
+  rerender(element: React.Element<unknown>): Promise<void>;
+  unmount(): Promise<void>;
+  debug(options?: DebugOptions): void
+  toJSON(): JsonElement | null;
+  container: TestInstance;
+  root: TestInstance | null;
+};
+```
+
+The `screen` object provides access to 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-helpers.md#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 main feature of `screen` is its queries for finding elements in the view hierarchy.
+
+See [Queries](./queries.md) for a complete list.
+
+#### Example
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+test('example', async () => {
+  await render(<MyComponent />);
+  const buttonStart = screen.getByRole('button', { name: 'start' });
+});
+```
+
+### `rerender`
+
+```ts
+function rerender(element: React.Element<unknown>): Promise<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.
+
+This method is async and uses async `act` internally to execute all pending React updates during updating. This works with async React features like `Suspense` boundaries and the `use()` hook.
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+test('async rerender test', async () => {
+  await render(<MyComponent initialData="first" />);
+
+  await screen.rerender(<MyComponent initialData="updated" />);
+  expect(screen.getByText('updated')).toBeOnTheScreen();
+});
+```
+
+### `unmount`
+
+```ts
+function unmount(): Promise<void>;
+```
+
+Unmount the in-memory tree, triggering the appropriate lifecycle events.
+
+This method is async and uses async `act` internally to execute all pending React updates during unmounting. This works with async React features like `Suspense` boundaries and the `use()` hook.
+
+> [!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
+
+You can provide a message that will be printed on top.
+
+```jsx
+await render(<Component />);
+screen.debug({ message: 'optional message' });
+```
+
+logs optional message and colored JSX:
+
+```jsx
+optional message
+
+<View
+  onPress={[Function bound fn]}
+>
+  <Text>Press me</Text>
+</View>
+```
+
+#### `mapProps` option
+
+```ts
+function debug({ mapProps: (props) => ({}) });
+```
+
+You can use the `mapProps` option to transform the props that will be printed :
+
+```jsx
+await render(<View style={{ backgroundColor: 'red' }} />);
+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(): JsonElement | null;
+```
+
+Get the rendered component JSON representation, e.g. for snapshot testing.
+
+### `container`
+
+```ts
+const container: TestInstance;
+```
+
+Returns a pseudo-element container whose children are the elements you asked to render. This is the root container element from [Test Renderer](https://github.com/mdjastrzebski/test-renderer).
+
+The `container` provides access to the entire rendered tree. Use it to query or manipulate the rendered output, similar to how `container` works in [React Testing Library](https://testing-library.com/docs/react-testing-library/other#container-1).
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+test('example', async () => {
+  await render(<MyComponent />);
+  // container contains the entire rendered tree
+  const container = screen.container;
+  expect(container).toBeTruthy();
+});
+```
+
+### `root`
+
+```ts
+const root: TestInstance | null;
+```
+
+Returns the rendered root [host element](../guides/testing-environment.md#host-and-composite-components), or `null` if nothing was rendered. This is the first child of the `container`, which represents the actual root element you rendered.
+
+This API is useful for component tests where you need to access the root host view without using `*ByTestId` queries or similar methods.
+
+> [!NOTE]
+> In rare cases where your root element is a `React.Fragment` with multiple children, the `container` will have more than one child, and `root` will return only the first one. In such cases, use `container.children` to access all rendered elements.
+
+```jsx
+import { render, screen } from '@testing-library/react-native';
+
+test('example', async () => {
+  await render(
+    <View testID="root-view">
+      <Text>Hello</Text>
+    </View>,
+  );
+  // root is the View element you rendered
+  expect(screen.root.props.testID).toBe('root-view');
+});
+```

package/docs/api/user-event.md

@@ -0,0 +1,295 @@
+# User Event interactions
+
+## Comparison with Fire Event API
+
+Fire Event is our original event simulation API. It can invoke **any event handler** declared on **either host or composite elements**. Suppose the element does not have `onEventName` event handler for the passed `eventName` event, or the element is disabled. In that case, Fire Event will traverse up the component tree, looking for an event handler on both host and composite elements along the way. By default, it will **not pass any event data**, but the user might provide it in the last argument.
+
+In contrast, User Event provides realistic event simulation for user interactions like `press` or `type`. Each interaction will trigger a **sequence of events** corresponding to React Native runtime behavior. These events will be invoked **only on host elements**, and **will automatically receive event data** corresponding to each event.
+
+If User Event supports a given interaction, prefer it over the Fire Event counterpart. It makes tests more realistic and reliable. When User Event doesn't support the event or you need to invoke event handlers on composite elements, use Fire Event.
+
+## `setup()`
+
+```ts
+userEvent.setup(options?: {
+  delay?: number;
+  advanceTimers?: (delay: number) => Promise<void> | void;
+})
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+```
+
+Creates a User Event object instance, which can be used to trigger events.
+
+### Options
+
+- `delay` controls the default delay between subsequent events, e.g., keystrokes.
+- `advanceTimers` is a time advancement utility function that should be used for fake timers. The default setup handles both real timers and Jest fake timers.
+
+## `press()`
+
+```ts
+press(
+  instance: TestInstance,
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.press(element);
+```
+
+Simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()`, which only calls the `onPress` prop, this function simulates the entire press interaction by reproducing the event sequence emitted by React Native runtime. It triggers additional events like `pressIn` and `pressOut`.
+
+This event will take a minimum of 130 ms to run due to the internal React Native logic. Consider using fake timers to speed up test execution for tests involving `press` and `longPress` interactions.
+
+## `longPress()`
+
+```ts
+longPress(
+  instance: TestInstance,
+  options?: { duration?: number }
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.longPress(element);
+```
+
+Simulates a long press user interaction. In React Native, the `longPress` event is emitted when the press duration exceeds the long press threshold (by default, 500 ms). In other aspects, this action behaves similarly to regular `press` action, e.g., by emitting `pressIn` and `pressOut` events. The press duration is customizable through the options, which is useful when using the `delayLongPress` prop.
+
+This event will, by default, take 500 ms to run. Due to internal React Native logic, it will take at least 130 ms regardless of the duration option passed. Consider using fake timers to speed up test execution for tests involving `press` and `longPress` interactions.
+
+### Options
+
+- `duration` - duration of the press in milliseconds. The default value is 500 ms.
+
+## `type()`
+
+```ts
+type(
+  instance: TestInstance,
+  text: string,
+  options?: {
+    skipPress?: boolean;
+    skipBlur?: boolean;
+    submitEditing?: boolean;
+  }
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.type(textInput, 'Hello world!');
+```
+
+Simulates focusing on a `TextInput` element, typing `text` one character at a time, and leaving the element.
+
+This function supports only host `TextInput` elements. Passing other element types will result in throwing an error.
+
+> [!NOTE]
+> This function will add text to the text already present in the text input (as specified by `value` or `defaultValue` props). To replace existing text, use [`clear()`](#clear) helper first.
+
+### Options
+
+- `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
+- `skipBlur` - if true, `endEditing` and `blur` events will not be triggered when typing is complete.
+- `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
+
+### Sequence of events
+
+The sequence of events depends on the `multiline` prop and the passed options.
+
+Events will not be emitted if the `editable` prop is set to `false`.
+
+**Entering the element**:
+
+- `pressIn` (optional)
+- `focus`
+- `pressOut` (optional)
+
+The `pressIn` and `pressOut` events are sent by default but can be skipped by passing the `skipPress: true` option.
+
+**Typing (for each character)**:
+
+- `keyPress`
+- `change`
+- `changeText`
+- `selectionChange`
+- `contentSizeChange` (only multiline)
+
+**Leaving the element**:
+
+- `submitEditing` (optional)
+- `endEditing`
+- `blur`
+
+The `submitEditing` event is skipped by default. It can sent by setting the `submitEditing: true` option.
+The `endEditing` and `blur` events can be skipped by passing the `skipBlur: true` option.
+
+## `clear()`
+
+```ts
+clear(
+  instance: TestInstance,
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.clear(textInput);
+```
+
+Simulates clearing the content of a `TextInput` element.
+
+This function supports only host `TextInput` elements. Passing other element types will result in throwing an error.
+
+### Sequence of events
+
+Events will not be emitted if the `editable` prop is set to `false`.
+
+**Entering the element**:
+
+- `focus`
+
+**Selecting all content**:
+
+- `selectionChange`
+
+**Pressing backspace**:
+
+- `keyPress`
+- `change`
+- `changeText`
+- `selectionChange`
+
+**Leaving the element**:
+
+- `endEditing`
+- `blur`
+
+## `paste()`
+
+```ts
+paste(
+  instance: TestInstance,
+  text: string,
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.paste(textInput, 'Text to paste');
+```
+
+Simulates pasting text into a `TextInput` element.
+
+This function supports only host `TextInput` elements. Passing other element types will result in throwing an error.
+
+### Sequence of events
+
+Events will not be emitted if the `editable` prop is set to `false`.
+
+**Entering the element**:
+
+- `focus`
+
+**Selecting all content**:
+
+- `selectionChange`
+
+**Pasting the text**:
+
+- `change`
+- `changeText`
+- `selectionChange`
+- `contentSizeChange` (only multiline)
+
+**Leaving the element**:
+
+- `endEditing`
+- `blur`
+
+## `scrollTo()` \
+
+```ts
+scrollTo(
+  instance: TestInstance,
+  options: {
+    y: number;
+    momentumY?: number;
+    contentSize?: { width: number; height: number };
+    layoutMeasurement?: { width: number; height: number };
+  } | {
+    x: number;
+    momentumX?: number;
+    contentSize?: { width: number; height: number };
+    layoutMeasurement?: { width: number; height: number };
+  }
+): Promise<void>
+```
+
+Example
+
+```ts
+const user = userEvent.setup();
+await user.scrollTo(scrollView, { y: 100, momentumY: 200 });
+```
+
+Simulates scrolling a host `ScrollView` element.
+
+This function supports only host `ScrollView` elements, passing other element types will result in an error. Note that `FlatList` is accepted as it renders to a host `ScrollView` element.
+
+Scroll interaction should match the `ScrollView` element direction:
+
+- for a vertical scroll view (default or `horizontal={false}`), you should pass only the `y` option (and optionally also `momentumY`).
+- for a horizontal scroll view (`horizontal={true}`), you should pass only the `x` option (and optionally `momentumX`).
+
+Each scroll interaction consists of a mandatory drag scroll part, which simulates the user dragging the scroll view with his finger (the `y` or `x` option). This may optionally be followed by a momentum scroll movement, which simulates the inertial movement of scroll view content after the user lifts his finger (`momentumY` or `momentumX` options).
+
+### Options
+
+- `y` - target vertical drag scroll offset
+- `x` - target horizontal drag scroll offset
+- `momentumY` - target vertical momentum scroll offset
+- `momentumX` - target horizontal momentum scroll offset
+- `contentSize` - passed to `ScrollView` events and enabling `FlatList` updates
+- `layoutMeasurement` - passed to `ScrollView` events and enabling `FlatList` updates
+
+User Event will generate several intermediate scroll steps to simulate user scroll interaction. You should not rely on exact number or values of these scrolls steps as they might be change in the future version.
+
+This function will remember where the last scroll ended, so subsequent scroll interaction will starts from that position. The initial scroll position will be assumed to be `{ y: 0, x: 0 }`.
+
+To simulate a `FlatList` (and other controls based on `VirtualizedList`) scrolling, you should pass the `contentSize` and `layoutMeasurement` options, which enable the underlying logic to update the currently visible window.
+
+### Sequence of events
+
+The sequence of events depends on whether the scroll includes an optional momentum scroll component.
+
+**Drag scroll**:
+
+- `contentSizeChange`
+- `scrollBeginDrag`
+- `scroll` (multiple events)
+- `scrollEndDrag`
+
+**Momentum scroll (optional)**:
+
+- `momentumScrollBegin`
+- `scroll` (multiple events)
+- `momentumScrollEnd`

package/docs/cookbook/async-events.md

@@ -0,0 +1,147 @@
+# Async Events
+
+## Summary
+
+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. **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.
+
+These utilities help you write reliable tests that properly handle timing in your application.
+
+### Example
+
+Consider a test for a user signing in with correct credentials:
+
+```javascript
+test('User can sign in with correct credentials', async () => {
+  // Typical test setup
+  const user = userEvent.setup();
+  await render(<App />);
+
+  // No need to use async here, components are already rendered
+  expect(screen.getByRole('header', { name: 'Sign in to Hello World App!' })).toBeOnTheScreen();
+
+  // Using await as User Event requires it
+  await user.type(screen.getByLabelText('Username'), 'admin');
+  await user.type(screen.getByLabelText('Password'), 'admin1');
+  await user.press(screen.getByRole('button', { name: 'Sign In' }));
+
+  // Using await as sign in operation is asynchronous
+  expect(await screen.findByRole('header', { name: 'Welcome admin!' })).toBeOnTheScreen();
+
+  // Follow-up assertions do not need to be async, as we already waited for sign in operation to complete
+  expect(
+    screen.queryByRole('header', { name: 'Sign in to Hello World App' }),
+  ).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Username')).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Password')).not.toBeOnTheScreen();
+});
+```
+
+## Async utilities
+
+There are several asynchronous utilities you might use in your tests.
+
+### `findBy*` queries
+
+The most common are the [`findBy*` queries](../api/queries.md#find-by). These are useful when waiting for a matching element to appear. They can be understood as a [`getBy*` queries](../api/queries.md#get-by) used in conjunction with a [`waitFor` function](../api/async-utilities.md#waitfor).
+
+They accept the same predicates as `getBy*` queries like `findByRole`, `findByTest`, etc. They also have a multiple elements variant called [`findAllBy*`](../api/queries.md#find-all-by).
+
+```typescript
+function findByRole: (
+  role: TextMatch,
+  queryOptions?: {
+    // Query specific options
+  }
+  waitForOptions?: {
+    timeout?: number;
+    interval?: number;
+    // ..
+  }
+): Promise<TestInstance>;
+```
+
+Each query has a default `timeout` value of 1000 ms and a default `interval` of 50 ms. Custom timeout and check intervals can be specified if needed, as shown below:
+
+#### Example
+
+```typescript
+const button = await screen.findByRole(
+  'button',
+  { name: 'Start' },
+  { timeout: 1000, interval: 50 },
+);
+```
+
+Alternatively, a default global `timeout` value can be set using the [`configure` function](../api/configuration.md#configure):
+
+```typescript
+configure({ asyncUtilTimeout: timeout });
+```
+
+### `waitFor` function
+
+The `waitFor` function is another option, serving as a lower-level utility in more advanced cases.
+
+```typescript
+function waitFor<T>(
+  expectation: () => T,
+  options?: {
+    timeout: number;
+    interval: number;
+  },
+): Promise<T>;
+```
+
+It accepts an `expectation` to be validated and repeats the check every defined interval until it no longer throws an error. Similarly to `findBy*` queries they accept `timeout` and `interval` options and have the same default values of 1000ms for timeout, and a checking interval of 50 ms.
+
+#### Example
+
+```typescript
+await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1));
+```
+
+If you want to use it with `getBy*` queries, use the `findBy*` queries instead, as they essentially do the same, but offer better developer experience.
+
+### `waitForElementToBeRemoved` function
+
+A specialized function, [`waitForElementToBeRemoved`](../api/async-utilities.md#waitforelementtoberemoved), is used to verify that a matching element was present but has since been removed.
+
+```typescript
+function waitForElementToBeRemoved<T>(
+  expectation: () => T,
+  options?: {
+    timeout: number;
+    interval: number;
+  },
+): Promise<T> {}
+```
+
+This function is, in a way, the negation of `waitFor` as it expects the initial expectation to be true (not throw an error), only to turn invalid (start throwing errors) on subsequent runs. It operates using the same `timeout` and `interval` parameters as `findBy*` queries and `waitFor`.
+
+#### Example
+
+```typescript
+await waitForElementToBeRemoved(() => getByText('Hello World'));
+```
+
+## Fake Timers
+
+Asynchronous tests can take long to execute due to the delays introduced by asynchronous operations. To mitigate this, fake timers can be used. These are particularly useful when delays are mere waits, such as the 130 milliseconds wait introduced by the UserEvent `press()` event due to React Native runtime behavior or simulated 1000 wait in a API call mock. Fake timers allow for precise fast-forwarding through these wait periods.
+
+Here are the basics of using [Jest fake timers](https://jestjs.io/docs/timer-mocks):
+
+- Enable fake timers with: `jest.useFakeTimers()`
+- Disable fake timers with: `jest.useRealTimers()`
+- Advance fake timers forward with: `jest.advanceTimersByTime(interval)`
+- Run **all timers** to completion with: `jest.runAllTimers()`
+- Run **currently pending timers** to completion with: `jest.runOnlyPendingTimers()`
+
+Be cautious when running all timers to completion as it might create an infinite loop if these timers schedule follow-up timers. In such cases, it's safer to use `jest.runOnlyPendingTimers()` to avoid ending up in an infinite loop of scheduled tasks.
+
+You can use both built-in Jest fake timers, as well as [Sinon.JS fake timers](https://sinonjs.org/releases/latest/fake-timers/).
+
+Note: you do not need to advance timers by hand when using User Event API, as it's automatically.