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

package/docs/api/fire-event.md

@@ -0,0 +1,165 @@
+# Fire Event API
+
+## `fireEvent`
+
+> [!NOTE]
+> For common events like `press` or `type`, use the [User Event API](./user-event.md). It simulates events more realistically 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.
+
+```ts
+function fireEvent(instance: TestInstance, eventName: string, ...data: unknown[]): Promise<unknown>;
+```
+
+The `fireEvent` API triggers event handlers on both host and composite components. It traverses the component tree bottom-up from the passed element to find an enabled event handler named `onXxx` where `xxx` is the event name.
+
+Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object.
+
+The base `fireEvent(instance, eventName, ...data)` API can pass multiple custom arguments to the handler. Convenience helpers such as `fireEvent.press` and `fireEvent.scroll` are different: they create a default event object and accept one optional object to merge into it.
+
+This function uses async `act` internally to execute all pending React updates during event handling.
+
+```jsx
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+test('fire changeText event', async () => {
+  const onEventMock = jest.fn();
+  await render(
+    // MyComponent renders TextInput which has a placeholder 'Enter details'
+    // and with `onChangeText` bound to handleChangeText
+    <MyComponent handleChangeText={onEventMock} />,
+  );
+
+  await fireEvent(screen.getByPlaceholderText('change'), 'onChangeText', 'ab');
+  expect(onEventMock).toHaveBeenCalledWith('ab');
+});
+```
+
+> [!NOTE]
+> `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, screen } from '@testing-library/react-native';
+
+const onBlurMock = jest.fn();
+
+await render(
+  <View>
+    <TextInput placeholder="my placeholder" onBlur={onBlurMock} />
+  </View>,
+);
+
+// you can omit the `on` prefix
+await fireEvent(screen.getByPlaceholderText('my placeholder'), 'blur');
+```
+
+FireEvent exposes convenience methods for common events like: `press`, `changeText`, `scroll`.
+
+### `fireEvent.press`
+
+> [!NOTE]
+> Use the User Event [`press()`](./user-event.md#press) helper instead. It simulates press interactions more realistically, including pressable support.
+
+```tsx
+fireEvent.press: (
+  instance: TestInstance,
+  eventProps?: Record<string, unknown>,
+) => Promise<void>
+```
+
+Builds a press event object, merges `eventProps` into it, and invokes the `press` handler on the element or nearest eligible parent.
+
+```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,
+  },
+};
+
+await render(
+  <View>
+    <TouchableOpacity onPress={onPressMock}>
+      <Text>Press me</Text>
+    </TouchableOpacity>
+  </View>,
+);
+
+await fireEvent.press(screen.getByText('Press me'), eventData);
+expect(onPressMock).toHaveBeenCalledWith(expect.objectContaining(eventData));
+```
+
+### `fireEvent.changeText`
+
+> [!NOTE]
+> Use the User Event [`type()`](./user-event.md#type) helper instead. It simulates text change interactions more realistically, including key-by-key typing, element focus, and other editing events.
+
+```tsx
+fireEvent.changeText: (
+  instance: TestInstance,
+  text: string,
+) => Promise<void>
+```
+
+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';
+
+await render(
+  <View>
+    <TextInput placeholder="Enter data" onChangeText={onChangeTextMock} />
+  </View>,
+);
+
+await fireEvent.changeText(screen.getByPlaceholderText('Enter data'), CHANGE_TEXT);
+```
+
+### `fireEvent.scroll`
+
+> [!NOTE]
+> Prefer [`user.scrollTo`](./user-event.md#scrollto) over `fireEvent.scroll` for `ScrollView`, `FlatList`, and `SectionList` components. User Event simulates events more realistically based on React Native runtime behavior.
+
+```tsx
+fireEvent.scroll: (
+  instance: TestInstance,
+  eventProps?: Record<string, unknown>,
+) => Promise<void>
+```
+
+Builds a scroll event object, merges `eventProps` into it, and invokes the `scroll` handler on the element or nearest eligible parent.
+
+#### 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,
+    },
+  },
+};
+
+await render(
+  <ScrollView testID="scroll-view" onScroll={onScrollMock}>
+    <Text>Content</Text>
+  </ScrollView>,
+);
+
+await fireEvent.scroll(screen.getByTestId('scroll-view'), eventData);
+```

package/docs/api/jest-matchers.md

@@ -0,0 +1,198 @@
+# Jest matchers
+
+This guide covers the built-in Jest matchers. These matchers make your tests easier to read and work better with accessibility features.
+
+## Setup
+
+No setup needed. Matchers are available when you import from `@testing-library/react-native`.
+
+## Checking element existence
+
+### `toBeOnTheScreen()`
+
+```ts
+expect(element).toBeOnTheScreen();
+```
+
+Checks if an element is attached to the element tree. If you have a reference to an element and it gets unmounted during the test, this assertion will fail.
+
+## Element Content
+
+### `toHaveTextContent()`
+
+```ts
+expect(element).toHaveTextContent(
+  text: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
+```
+
+Checks if an element has the specified text content. Accepts `string` or `RegExp`, with optional [text match options](./queries.md#text-match-options) like `exact` and `normalizer`.
+
+### `toContainElement()`
+
+```ts
+expect(container).toContainElement(
+  instance: TestInstance | null,
+)
+```
+
+Checks if a container element contains another element.
+
+### `toBeEmptyElement()`
+
+```ts
+expect(element).toBeEmptyElement();
+```
+
+Checks if an element has no child elements or text content.
+
+## Checking element state
+
+### `toHaveDisplayValue()`
+
+```ts
+expect(element).toHaveDisplayValue(
+  value: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
+```
+
+Checks if a `TextInput` has the specified display value. Accepts `string` or `RegExp`, with optional [text match options](./queries.md#text-match-options) like `exact` and `normalizer`.
+
+### `toHaveAccessibilityValue()`
+
+```ts
+expect(element).toHaveAccessibilityValue(
+  value: {
+    min?: number;
+    max?: number;
+    now?: number;
+    text?: string | RegExp;
+  },
+)
+```
+
+Checks if an element has the specified accessible value.
+
+The matcher reads accessibility values from `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`, and `accessibilityValue` props. It only checks the values you specify, so the element can have other accessibility value entries and still match.
+
+For the `text` entry, you can use a string or `RegExp`.
+
+### `toBeEnabled()` / `toBeDisabled`
+
+```ts
+expect(element).toBeEnabled();
+expect(element).toBeDisabled();
+```
+
+Checks if an element is enabled or disabled from `aria-disabled` or `accessibilityState.disabled` props. An element is disabled if it or any ancestor is disabled.
+
+> [!NOTE]
+> These matchers are opposites. Both are available so you can avoid double negations like `expect(element).not.toBeDisabled()`.
+
+### `toBeSelected()`
+
+```ts
+expect(element).toBeSelected();
+```
+
+Checks if an element is selected from `aria-selected` or `accessibilityState.selected` props.
+
+### `toBeChecked()` / `toBePartiallyChecked()`
+
+```ts
+expect(element).toBeChecked();
+expect(element).toBePartiallyChecked();
+```
+
+Checks if an element is checked or partially checked from `aria-checked` or `accessibilityState.checked` props.
+
+> [!NOTE]
+>
+> - `toBeChecked()` only works on `Switch` host elements and elements with `checkbox`, `radio`, or `switch` role.
+> - `toBePartiallyChecked()` only works on elements with `checkbox` role.
+
+### `toBeExpanded()` / `toBeCollapsed()`
+
+```ts
+expect(element).toBeExpanded();
+expect(element).toBeCollapsed();
+```
+
+Checks if an element is expanded or collapsed from `aria-expanded` or `accessibilityState.expanded` props.
+
+> [!NOTE]
+> These matchers are opposites for expandable elements (those with explicit `aria-expanded` or `accessibilityState.expanded` props). For non-expandable elements, neither matcher will pass.
+
+### `toBeBusy()`
+
+```ts
+expect(element).toBeBusy();
+```
+
+Checks if an element is busy from `aria-busy` or `accessibilityState.busy` props.
+
+## Checking element style
+
+### `toBeVisible()`
+
+```ts
+expect(element).toBeVisible();
+```
+
+Checks if an element is visible.
+
+An element is invisible if it or any ancestor has `display: none` or `opacity: 0` styles, or if it's hidden from accessibility.
+
+### `toHaveStyle()`
+
+```ts
+expect(element).toHaveStyle(
+  style: StyleProp<Style>,
+)
+```
+
+Checks if an element has specific styles.
+
+## Other matchers
+
+### `toHaveAccessibleName()`
+
+```ts
+expect(element).toHaveAccessibleName(
+  name?: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
+```
+
+Checks if an element has the specified accessible name. Accepts `string` or `RegExp`, with optional [text match options](./queries.md#text-match-options) like `exact` and `normalizer`.
+
+The accessible name comes from `aria-labelledby`, `accessibilityLabelledBy`, `aria-label`, and `accessibilityLabel` props. For `Image` elements, the `alt` prop is also used. If none are present, the element's text content is used.
+
+When `accessibilityLabelledBy` references multiple elements with an array, their text content is joined with spaces in the referenced order and matched as a single accessible name. `aria-labelledby` follows React Native's single `nativeID` value behavior.
+
+Without a `name` parameter (or with `undefined`), it only checks whether the element has any accessible name.
+
+### `toHaveProp()`
+
+```ts
+expect(element).toHaveProp(
+  name: string,
+  value?: unknown,
+)
+```
+
+Checks if an element has a prop. Without a `value` (or with `undefined`), it only checks if the prop exists. With a `value`, it checks if the prop's value matches.
+
+> [!NOTE]
+> Use this matcher as a last resort when other matchers don't fit your needs.

package/docs/api/other-helpers.md

@@ -0,0 +1,94 @@
+# Other helpers
+
+## `within`
+
+```jsx
+function within(instance: TestInstance): Queries {}
+```
+
+`within` performs [queries](./queries.md) scoped to given element.
+
+> [!NOTE]
+> Please note that additional `render` specific operations like `rerender`, `unmount`, `debug`, `toJSON` are _not_ included.
+
+```jsx
+const detailsScreen = within(screen.getByHintText('Details Screen'));
+expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen();
+expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen();
+expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen();
+await expect(detailsScreen.findByHintText('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`
+
+```ts
+function act<T>(callback: () => T | Promise<T>): Promise<T>;
+```
+
+Wraps code that causes React state updates to ensure all updates are processed before assertions. By default any `render`, `rerender`, `fireEvent`, and `waitFor` calls are wrapped by this function, so there is no need to wrap it manually.
+
+**In v14, `act` is now async by default and always returns a Promise**. This works with async React features like `Suspense` boundaries and the `use()` hook. All pending React updates are executed before the Promise resolves.
+
+```ts
+import { act } from '@testing-library/react-native';
+
+it('should update state', async () => {
+  await act(() => {
+    setState('new value');
+  });
+  expect(state).toBe('new value');
+});
+```
+
+**Note**: Even if your callback is synchronous, you should still use `await act(...)` as `act` now always returns a Promise.
+
+Consult our [Understanding Act function](../guides/understanding-act.md) document for more understanding of its intricacies.
+
+## `cleanup`
+
+```ts
+function cleanup(): Promise<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(async () => {
+  await cleanup();
+});
+
+it('renders a view', async () => {
+  await render(<View />);
+  // ...
+});
+```
+
+The `afterEach(cleanup)` call also works in `describe` blocks:
+
+```jsx
+describe('when logged in', () => {
+  afterEach(async () => {
+    await cleanup();
+  });
+
+  it('renders the user', async () => {
+    await render(<SiteHeader />);
+    // ...
+  });
+});
+```
+
+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).

package/docs/api/overview.md

@@ -0,0 +1,18 @@
+# API Overview
+
+React Native Testing Library consists of following APIs:
+
+- [`render` function](./render.md) - render your UI components for testing purposes
+- [`screen` object](./screen.md) - access rendered UI:
+  - [Queries](./queries.md) - find relevant components by various predicates: role, text, test ids, etc
+  - Lifecycle methods: [`rerender`](./screen.md#rerender), [`unmount`](./screen.md#unmount)
+  - Helpers: [`debug`](./screen.md#debug), [`toJSON`](./screen.md#tojson), [`root`](./screen.md#root)
+- [Jest matchers](./jest-matchers.md) - validate assumptions about your UI
+- [User Event](./user-event.md) - simulate common user interactions like [`press`](./user-event.md#press) or [`type`](./user-event.md#type) in a realistic way
+- [Fire Event](./fire-event.md) - simulate any component event in a simplified way purposes
+- Misc APIs:
+  - [`renderHook` function](./render-hook.md) - render hooks for testing
+  - [Async utils](./async-utilities.md): `findBy*` queries, `waitFor`, `waitForElementToBeRemoved`
+  - [Configuration](./configuration.md): `configure`, `resetToDefaults`
+  - [Accessibility](./accessibility.md): `isHiddenFromAccessibility`
+  - [Other](./other-helpers.md): `within`, `act`, `cleanup`