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

package/docs/guides/migration-v14.md

@@ -0,0 +1,553 @@
+import { PackageManagerTabs } from '@rspress/core/theme';
+
+# Migration to 14.x
+
+This guide describes the migration to React Native Testing Library version 14 from version 13.x.
+
+## Overview
+
+RNTL v14 drops support for React 18 and adopts React 19's async rendering model. Here's what changed:
+
+- React 19.0.0+ and React Native 0.78+ are now required
+- Node.js `^22.13.0 || >=24` is now required
+- `render`, `renderHook`, `fireEvent`, and `act` are now async
+- Switched from deprecated [React Test Renderer](https://reactjs.org/docs/test-renderer.html) to [Test Renderer](https://github.com/mdjastrzebski/test-renderer)
+- Removed deprecated APIs: `update`, `getQueriesForElement`, `UNSAFE_root`, `concurrentRoot` option, `createNodeMock` option
+- Reintroduced `container` API, which is now safe to use
+
+> [!INFO] React 18 Users
+> If you need to support React 18, please continue using RNTL v13.x.
+
+## Quick Migration
+
+We provide codemods to automate most of the migration:
+
+**Step 1: Update dependencies**
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-update-deps --target .\nnpm install',
+    yarn: 'yarn dlx codemod@latest rntl-v14-update-deps --target .\nyarn install',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-update-deps --target .\npnpm install',
+    bun: 'bunx codemod@latest rntl-v14-update-deps --target .\nbun install',
+  }}
+/>
+
+**Step 2: Update test code to async**
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-async-functions --target ./src',
+    yarn: 'yarn dlx codemod@latest rntl-v14-async-functions --target ./src',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-async-functions --target ./src',
+    bun: 'bunx codemod@latest rntl-v14-async-functions --target ./src',
+  }}
+/>
+
+After running the codemods, review the changes and run your tests.
+
+If your project uses coding agents, add the RNTL package-docs instruction snippet from the [Quick Start](./quick-start.md#agent-docs-in-the-package) so agents read the docs that match your installed package version.
+
+## Breaking Changes
+
+### Supported React, React Native, and Node.js versions
+
+**This version requires React 19+, React Native 0.78+, and Node.js `^22.13.0 || >=24`.** If you need to support React 18, please use the latest v13.x version.
+
+| RNTL Version | React Version | React Native Version | Node.js Version    |
+| ------------ | ------------- | -------------------- | ------------------ |
+| v14.x        | >= 19.0.0     | >= 0.78              | ^22.13.0 \|\| >=24 |
+| v13.x        | >= 18.0.0     | >= 0.71              | >= 18              |
+
+### Test Renderer replaces React Test Renderer
+
+In v14, React Native Testing Library uses [Test Renderer](https://github.com/mdjastrzebski/test-renderer) instead of the deprecated [React Test Renderer](https://reactjs.org/docs/test-renderer.html). Test Renderer works with React 19 and has better TypeScript support.
+
+**What changed:**
+
+- The underlying renderer is now Test Renderer instead of React Test Renderer
+- This is mostly an internal change; your tests should work without modifications in most cases
+- Type definitions now use [`TestInstance`](https://github.com/mdjastrzebski/test-renderer#test-instance) from Test Renderer instead of `ReactTestInstance`
+- Test Renderer 1.x is required as a peer dependency. Use the recommended Test Renderer version for your React 19 minor version.
+
+#### Recommended Test Renderer versions
+
+Choose the Test Renderer version that matches your React 19 minor version:
+
+| React version | Recommended Test Renderer version | Notable React features                            |
+| ------------- | --------------------------------- | ------------------------------------------------- |
+| `19.2`        | `test-renderer@1.2`               | `<Activity />`, `useEffectEvent`                  |
+| `19.1`        | `test-renderer@1.1`               | Owner Stack support, updated `useId()` format     |
+| `19.0`        | `test-renderer@1.0`               | Actions, `useActionState`, `useOptimistic`, `use` |
+
+Using an older Test Renderer line can prevent RNTL from supporting newer React 19 features in your tests. Using a newer Test Renderer line than your React version can produce peer dependency warnings, or an install error with `npm`.
+
+See the [Test Renderer React 19 compatibility lines](https://github.com/mdjastrzebski/test-renderer#react-19-compatibility-lines) for the latest recommendations.
+
+**Migration:**
+
+#### 1. Update dependencies
+
+Run codemod for updating dependencies:
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-update-deps\nnpm install',
+    yarn: 'yarn dlx codemod@latest rntl-v14-update-deps\nyarn install',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-update-deps\npnpm install',
+    bun: 'bunx codemod@latest rntl-v14-update-deps\nbun install',
+  }}
+/>
+
+##### Manual changes
+
+Remove React Test Renderer and its type definitions from your dev dependencies, and add the Test Renderer line that matches your React minor version:
+
+<PackageManagerTabs
+command={{
+    npm: 'npm uninstall react-test-renderer @types/react-test-renderer\nnpm install -D test-renderer@1.2',
+    yarn: 'yarn remove react-test-renderer @types/react-test-renderer\nyarn add -D test-renderer@1.2',
+    pnpm: 'pnpm remove react-test-renderer @types/react-test-renderer\npnpm add -D test-renderer@1.2',
+    bun: 'bun remove react-test-renderer @types/react-test-renderer\nbun add -D test-renderer@1.2',
+  }}
+/>
+
+The commands above use `test-renderer@1.2` for React 19.2. Use `test-renderer@1.1` for React 19.1, or `test-renderer@1.0` for React 19.0.
+
+#### 2. Update type imports (if needed)
+
+If you were directly importing types from React Test Renderer, you may need to update your imports:
+
+```ts
+// Before (v13)
+import type { ReactTestInstance } from 'react-test-renderer';
+
+// After (v14)
+import type { TestInstance } from 'test-renderer';
+```
+
+**Note:** Most users won't need to update type imports, as React Native Testing Library now exports the necessary types directly.
+
+See the [Test Renderer documentation](https://github.com/mdjastrzebski/test-renderer) for more.
+
+### Async APIs by Default
+
+With React 18 support dropped, RNTL v14 uses React 19's async rendering model. The following functions are now async by default:
+
+- `render()` → returns `Promise<RenderResult>`
+- `rerender()` and `unmount()` → return `Promise<void>`
+- `renderHook()` → returns `Promise<RenderHookResult>`
+- `fireEvent()` and helpers (`press`, `changeText`, `scroll`) → return `Promise<void>`
+- `act()` → always returns `Promise<T>`
+
+> [!TIP] Already using async APIs?
+> If you adopted the async APIs introduced in RNTL v13.3 (`renderAsync`, `fireEventAsync`, `renderHookAsync`), rename them to their non-async counterparts (`render`, `fireEvent`, `renderHook`). The async versions have been removed since the standard APIs are now async by default.
+
+#### `render` is now async
+
+In v14, `render` is async by default and returns a Promise. This allows proper support for `Suspense` boundaries and the `use()` hook.
+
+**Before (v13):**
+
+```ts
+import { render, screen } from '@testing-library/react-native';
+
+it('should render component', () => {
+  render(<MyComponent />);
+  expect(screen.getByText('Hello')).toBeOnTheScreen();
+});
+```
+
+**After (v14):**
+
+```ts
+import { render, screen } from '@testing-library/react-native';
+
+it('should render component', async () => {
+  await render(<MyComponent />);
+  expect(screen.getByText('Hello')).toBeOnTheScreen();
+});
+```
+
+See the [`render` API documentation](../api/render.md).
+
+#### `renderHook` is now async
+
+In v14, `renderHook` is async by default and returns a Promise.
+
+**Before (v13):**
+
+```ts
+import { renderHook } from '@testing-library/react-native';
+
+it('should test hook', () => {
+  const { result, rerender } = renderHook(() => useMyHook());
+
+  rerender(newProps);
+  unmount();
+});
+```
+
+**After (v14):**
+
+```ts
+import { renderHook } from '@testing-library/react-native';
+
+it('should test hook', async () => {
+  const { result, rerender } = await renderHook(() => useMyHook());
+
+  await rerender(newProps);
+  await unmount();
+});
+```
+
+See the [`renderHook` API documentation](../api/render-hook.md).
+
+#### `fireEvent` is now async
+
+In v14, `fireEvent` and its helpers (`press`, `changeText`, `scroll`) are async by default and return a Promise.
+
+**Before (v13):**
+
+```ts
+import { fireEvent, screen } from '@testing-library/react-native';
+
+it('should press button', () => {
+  render(<MyComponent />);
+  fireEvent.press(screen.getByText('Press me'));
+  expect(onPress).toHaveBeenCalled();
+});
+```
+
+**After (v14):**
+
+```ts
+import { fireEvent, screen } from '@testing-library/react-native';
+
+it('should press button', async () => {
+  await render(<MyComponent />);
+  await fireEvent.press(screen.getByText('Press me'));
+  expect(onPress).toHaveBeenCalled();
+});
+```
+
+`fireEvent.press()` and `fireEvent.scroll()` now create default synthetic native event objects. If you pass event props, they are deep-merged into the default event object:
+
+```ts
+await fireEvent.press(screen.getByText('Press me'), {
+  nativeEvent: { pageX: 20, pageY: 30 },
+});
+
+expect(onPress).toHaveBeenCalledWith(
+  expect.objectContaining({
+    nativeEvent: expect.objectContaining({ pageX: 20, pageY: 30 }),
+  }),
+);
+```
+
+If your v13 assertions expected the handler to receive exactly the object you passed to `fireEvent.press()` or `fireEvent.scroll()`, update them to use partial matching.
+
+#### `act` is now async
+
+In v14, `act` is async by default and always returns a Promise. You should always `await` the result of `act()`.
+
+**What changed:**
+
+- `act` now always returns `Promise<T>` instead of `T | Thenable<T>`
+- `act` should always be awaited
+
+> [!NOTE]
+> The transition to async `act` may prevent testing very short transient states, as awaiting `act` will flush all pending updates before returning.
+
+**Before (v13):**
+
+```ts
+import { act } from '@testing-library/react-native';
+
+it('should update state', () => {
+  act(() => {
+    setState('new value');
+  });
+  expect(state).toBe('new value');
+});
+```
+
+**After (v14):**
+
+```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.
+
+See the [`act` API documentation](../api/other-helpers.md#act).
+
+#### Why async APIs?
+
+The async APIs properly handle `Suspense` boundaries and the `use()` hook, and ensure all pending React updates complete before assertions run. This matches React 19's async rendering model.
+
+### Removed APIs
+
+#### `update` alias removed
+
+The `update` alias for `rerender` has been removed. Use `rerender` instead:
+
+```ts
+// Before (v13)
+screen.update(<MyComponent />);
+const { update } = render(<MyComponent />);
+update(<MyComponent newProp />);
+
+// After (v14)
+await screen.rerender(<MyComponent />);
+const { rerender } = await render(<MyComponent />);
+await rerender(<MyComponent newProp />);
+```
+
+#### `getQueriesForElement` export removed
+
+The `getQueriesForElement` export alias for `within` has been removed. Use `within` instead:
+
+```ts
+// Before (v13)
+import { getQueriesForElement } from '@testing-library/react-native';
+
+const queries = getQueriesForElement(element);
+
+// After (v14)
+import { within } from '@testing-library/react-native';
+
+const queries = within(element);
+```
+
+**Note:** `getQueriesForElement` was just an alias for `within`, so the functionality is identical - only the import needs to change.
+
+#### `UNSAFE_root` removed
+
+`UNSAFE_root` has been removed. Use `container` to access the pseudo-element container, or `root` to access the first rendered host element:
+
+```ts
+// Before (v13)
+const unsafeRoot = screen.UNSAFE_root;
+
+// After (v14)
+const container = screen.container; // pseudo-element container
+const root = screen.root; // first rendered host element
+```
+
+#### Legacy `UNSAFE_*` queries removed
+
+The legacy `UNSAFE_getAllByType`, `UNSAFE_getByType`, `UNSAFE_getAllByProps`, and `UNSAFE_getByProps` queries have been removed. These queries could return composite (user-defined) components, which is no longer supported with [Test Renderer](https://github.com/mdjastrzebski/test-renderer) as it only renders host elements.
+
+If you were using these legacy queries, you should refactor your tests to use the standard queries (`getByRole`, `getByText`, `getByTestId`, etc.) which target host elements.
+
+```ts
+// Before (v13)
+const buttons = screen.UNSAFE_getAllByType(Button);
+const input = screen.UNSAFE_getByProps({ placeholder: 'Enter text' });
+
+// After (v14)
+const buttons = screen.getAllByRole('button');
+const input = screen.getByPlaceholderText('Enter text');
+```
+
+#### `concurrentRoot` option removed
+
+The `concurrentRoot` option has been removed from both `render` options and `configure` function. In v14, concurrent rendering is always enabled, since it's the standard rendering mode for React 19 and React Native's New Architecture.
+
+```ts
+// Before (v13)
+render(<MyComponent />, { concurrentRoot: true });  // Enable concurrent mode
+render(<MyComponent />, { concurrentRoot: false }); // Disable concurrent mode
+configure({ concurrentRoot: false });               // Disable globally
+
+// After (v14)
+await render(<MyComponent />); // Always uses concurrent rendering
+```
+
+**Migration:** Remove any `concurrentRoot` options from your `render` calls and `configure` function. If you were setting `concurrentRoot: true`, just remove the option. If you were setting `concurrentRoot: false` to disable concurrent rendering, this is no longer supported in v14.
+
+#### `createNodeMock` option removed
+
+The `createNodeMock` render option has been removed. It was previously passed through to React Test Renderer, but the v14 Test Renderer integration does not support this option.
+
+```ts
+// Before (v13)
+render(<MyComponent />, {
+  createNodeMock: (element) => {
+    if (element.type === TextInput) {
+      return { focus: jest.fn() };
+    }
+    return {};
+  },
+});
+
+// After (v14)
+await render(<MyComponent />);
+```
+
+If you used `createNodeMock` to mock imperative refs, prefer testing user-visible behavior and mock the component or native module at the boundary where the ref behavior is introduced.
+
+### `container` API reintroduced
+
+In v14, the `container` API has been reintroduced and is now safe to use. Previously, `container` was renamed to `UNSAFE_root` in v12 due to behavioral differences from React Testing Library's `container`. Now `container` returns a pseudo-element container whose children are the elements you rendered, consistent with React Testing Library's behavior.
+
+**What changed:**
+
+- `screen.container` is now available and safe to use
+- `container` returns a pseudo-element container from Test Renderer
+- The container's children are the elements you rendered
+- `UNSAFE_root` has been removed
+
+**Before (v13):**
+
+```ts
+import { render, screen } from '@testing-library/react-native';
+
+it('should access root', () => {
+  render(<MyComponent />);
+  // UNSAFE_root was the only way to access the container
+  const root = screen.UNSAFE_root;
+});
+```
+
+**After (v14):**
+
+```ts
+import { render, screen } from '@testing-library/react-native';
+
+it('should access container', async () => {
+  await render(<MyComponent />);
+  // container is now safe and available
+  const container = screen.container;
+  // root is the first child of container
+  const root = screen.root;
+});
+```
+
+See the [`screen` API documentation](../api/screen.md#container).
+
+### Text string validation enforced by default
+
+In v14, Test Renderer enforces React Native's requirement that text strings must be rendered within a `<Text>` component. The `unstable_validateStringsRenderedWithinText` option has been removed from `RenderOptions` since this validation is now always on.
+
+**What changed:**
+
+- Text string validation is now always enabled and cannot be disabled
+- The `unstable_validateStringsRenderedWithinText` option has been removed
+- Tests will now throw `Invariant Violation: Text strings must be rendered within a <Text> component` errors when attempting to render strings outside of `<Text>` components, matching React Native's runtime behavior
+
+**Migration:**
+
+If you were using `unstable_validateStringsRenderedWithinText: true` in your render options, you can simply remove this option as the validation is now always enabled:
+
+```ts
+// Before (v13)
+render(<MyComponent />, {
+  unstable_validateStringsRenderedWithinText: true,
+});
+
+// After (v14)
+await render(<MyComponent />);
+// Validation is now always enabled
+```
+
+If you were relying on the previous behavior where strings could be rendered outside of `<Text>` components, you'll need to fix your components to wrap strings in `<Text>` components, as this matches React Native's actual runtime behavior.
+
+### Hidden Suspense and Activity content
+
+When React keeps previously rendered content hidden, such as suspended content or React 19.2 `<Activity mode="hidden">`, RNTL now applies React Native-like hidden props to the affected instances. In practice, hidden instances receive `display: 'none'`, preserving existing styles by appending the hidden style.
+
+This makes visibility queries and matchers behave closer to runtime behavior:
+
+- default queries do not match hidden instances
+- queries with `{ includeHiddenElements: true }` can still find hidden instances
+- `toBeVisible()` treats these instances as hidden
+
+### Accessible name changes
+
+Accessible name calculation has been updated to better match React Native behavior:
+
+- `aria-labelledby` and `accessibilityLabelledBy` still take precedence over explicit labels
+- `aria-label` and `accessibilityLabel` take precedence over text content
+- `Image` `alt` is used as an accessible label
+- a root `TextInput` can use its `placeholder` as its accessible name
+- child accessible names are concatenated with spaces
+- child `TextInput` placeholders are not used when computing a parent's accessible name
+
+This affects `getByRole(..., { name })` and `toHaveAccessibleName()`. If a v13 role query matched because descendant text or label queries were used as a fallback, update the test to match the element's computed accessible name directly or query the descendant element instead.
+
+### Unknown options now warn
+
+RNTL now logs a warning when unknown options are passed to `configure`, `render`, `renderHook`, or `userEvent.setup`. This helps catch stale v13 options and misspellings during migration.
+
+For example, after removing `concurrentRoot`, `createNodeMock`, or `unstable_validateStringsRenderedWithinText`, make sure those options are not still being passed through shared test helpers.
+
+## Codemods
+
+Two codemods are available to automate the migration. Both are safe to run multiple times - they only transform code that hasn't been migrated yet.
+
+### `rntl-v14-update-deps`
+
+Updates your `package.json`:
+
+- Removes React Test Renderer (`react-test-renderer` and `@types/react-test-renderer`)
+- Adds Test Renderer (`test-renderer`) using the current recommended 1.x line
+- Updates `@testing-library/react-native` to the v14 version
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-update-deps --target .\nnpm install',
+    yarn: 'yarn dlx codemod@latest rntl-v14-update-deps --target .\nyarn install',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-update-deps --target .\npnpm install',
+    bun: 'bunx codemod@latest rntl-v14-update-deps --target .\nbun install',
+  }}
+/>
+
+### `rntl-v14-async-functions`
+
+Transforms test files:
+
+- Adds `await` to `render()`, `act()`, `renderHook()`, `fireEvent()` calls
+- Makes test functions async when needed
+- Handles `screen.rerender()`, `screen.unmount()`, and renderer methods
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-async-functions --target ./src',
+    yarn: 'yarn dlx codemod@latest rntl-v14-async-functions --target ./src',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-async-functions --target ./src',
+    bun: 'bunx codemod@latest rntl-v14-async-functions --target ./src',
+  }}
+/>
+
+#### Custom render functions
+
+If you have custom render helpers (like `renderWithProviders`), you can specify them using the `customRenderFunctions` parameter. The codemod will then also transform calls to these functions:
+
+<PackageManagerTabs
+command={{
+    npm: 'npx codemod@latest rntl-v14-async-functions \\\n  --target ./src \\\n  --param customRenderFunctions="renderWithProviders,renderWithTheme"',
+    yarn: 'yarn dlx codemod@latest rntl-v14-async-functions \\\n  --target ./src \\\n  --param customRenderFunctions="renderWithProviders,renderWithTheme"',
+    pnpm: 'pnpm dlx codemod@latest rntl-v14-async-functions \\\n  --target ./src \\\n  --param customRenderFunctions="renderWithProviders,renderWithTheme"',
+    bun: 'bunx codemod@latest rntl-v14-async-functions \\\n  --target ./src \\\n  --param customRenderFunctions="renderWithProviders,renderWithTheme"',
+  }}
+/>
+
+This will add `await` to your custom render calls and make the containing test functions async, just like it does for the standard `render` function.
+
+#### Limitations
+
+- Helper functions defined in test files are not transformed by default
+- Namespace imports (`import * as RNTL`) are not handled
+
+## Full Changelog
+
+https://github.com/callstack/react-native-testing-library/compare/v13.3.3...v14.0.0

package/docs/guides/quick-start.md

@@ -0,0 +1,77 @@
+import { PackageManagerTabs } from '@rspress/core/theme';
+
+# Quick Start
+
+## Installation
+
+Open a Terminal in your project's folder and run:
+
+<PackageManagerTabs
+command={{
+    npm: 'npm install -D @testing-library/react-native',
+    yarn: 'yarn add -D @testing-library/react-native',
+    pnpm: 'pnpm add -D @testing-library/react-native',
+    bun: 'bun add -D @testing-library/react-native',
+  }}
+/>
+
+This library has a peer dependency on [Test Renderer](https://github.com/mdjastrzebski/test-renderer). Make sure to install it:
+
+<PackageManagerTabs
+command={{
+    npm: 'npm install -D test-renderer',
+    yarn: 'yarn add -D test-renderer',
+    pnpm: 'pnpm add -D test-renderer',
+    bun: 'bun add -D test-renderer',
+  }}
+/>
+
+Test Renderer has better compatibility with React 19 and improved type safety compared to the deprecated [React Test Renderer](https://reactjs.org/docs/test-renderer.html).
+
+## Agent docs in the package
+
+RNTL ships package-specific documentation for coding agents in `node_modules/@testing-library/react-native/docs/`.
+Add this snippet to your project's `AGENTS.md` or `CLAUDE.md` file so agents use the docs for the installed package version:
+
+```md
+# React Native Testing Library in this project
+
+This project uses `@testing-library/react-native`. Its APIs and testing conventions can differ from your training data.
+Before writing or changing RNTL tests, read the relevant guide in
+`node_modules/@testing-library/react-native/docs/`, starting with
+`node_modules/@testing-library/react-native/docs/guides/llm-guidelines.md`.
+Prefer those package docs over stale assumptions, and follow deprecation notices.
+```
+
+### Jest matchers
+
+RNTL automatically extends Jest with React Native-specific matchers. The only thing you need to do is to import anything from `@testing-library/react-native` which you already need to do to access the `render` function.
+
+### ESLint plugin
+
+Set up [`eslint-plugin-testing-library`](https://github.com/testing-library/eslint-plugin-testing-library) to avoid common Testing Library mistakes and bad practices.
+
+Install the plugin (assuming you already have `eslint` installed & configured):
+
+<PackageManagerTabs
+command={{
+    npm: 'npm install -D eslint-plugin-testing-library',
+    yarn: 'yarn add -D eslint-plugin-testing-library',
+    pnpm: 'pnpm add -D eslint-plugin-testing-library',
+    bun: 'bun add -D eslint-plugin-testing-library',
+  }}
+/>
+
+Then, add this to your ESLint config (e.g., `.eslintrc.js`). Extend the `react` plugin:
+
+```js title=.eslintrc.js
+module.exports = {
+  overrides: [
+    {
+      // Test files only
+      files: ['**/__tests__/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
+      extends: ['plugin:testing-library/react'],
+    },
+  ],
+};
+```