chore: v14 RC preparations

CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to React Native Testing Library will be documented in this file, starting
+with v14.
+
+## 14.0.0
+
+### Migration guide
+
+See the [Migration to 14.x](./website/docs/14.x/docs/start/migration-v14.mdx) guide for
+step-by-step upgrade instructions, codemods, and before/after examples.
+
+### Breaking changes
+
+- Dropped support for React 18. React 19.0.0 or newer is now required.
+- Raised the minimum supported React Native version to 0.78.
+- Raised the minimum supported Node.js version to `^22.13.0 || >=24`.
+- Replaced the deprecated React Test Renderer with
+  [Test Renderer](https://github.com/mdjastrzebski/test-renderer).
+- Added a peer dependency on Test Renderer 1.x. Install the Test Renderer compatibility line
+  that matches your React 19 minor version.
+- Made the core rendering and event APIs async by default:
+  - `render()` now returns `Promise<RenderResult>`.
+  - `renderHook()` now returns `Promise<RenderHookResult>`.
+  - `fireEvent()` and its helpers now return `Promise<void>`.
+  - `act()` now always returns a Promise and should always be awaited.
+- Removed the `renderAsync`, `renderHookAsync`, and `fireEventAsync` APIs. Use `render`,
+  `renderHook`, and `fireEvent` instead.
+- Removed the `update` alias. Use `rerender` instead.
+- Removed the `getQueriesForElement` alias. Use `within` instead.
+- Removed `UNSAFE_root`. Use `container` for the pseudo-element container or `root` for
+  the first rendered host element.
+- Removed legacy `UNSAFE_*` queries:
+  - `UNSAFE_getAllByType`
+  - `UNSAFE_getByType`
+  - `UNSAFE_getAllByProps`
+  - `UNSAFE_getByProps`
+- Removed the `concurrentRoot` render and configuration option. Concurrent rendering is
+  always enabled in v14.
+- Removed the `createNodeMock` render option, which is not supported by the new Test Renderer
+  integration.
+- Removed the `unstable_validateStringsRenderedWithinText` render option. Text string
+  validation is now always enabled.
+
+### Notable changes
+
+- Reintroduced the `container` API as a safe pseudo-element container, aligned with React
+  Testing Library semantics.
+- Query results and the rendered element tree now expose host elements only. Composite
+  components are no longer visible through the test tree.
+- Type definitions now use `TestInstance` from Test Renderer instead of
+  `ReactTestInstance` from React Test Renderer.
+- Suspended or hidden instances are now represented with React Native-like hidden props, such
+  as `display: 'none'`, so visibility queries and matchers behave closer to runtime behavior.
+- `fireEvent.press()` and `fireEvent.scroll()` now pass default synthetic native event objects
+  to handlers and deep-merge any event props supplied by the test.
+- Accessible name calculation now follows React Native inputs more closely, including
+  `TextInput` placeholder handling, child accessible name concatenation, and stricter
+  `getByRole(..., { name })` matching.
+- `configure`, `render`, `renderHook`, and `userEvent.setup` now warn when unknown options are
+  passed, helping catch stale or misspelled options during migration.
+- Text strings rendered outside of React Native `<Text>` components now throw, matching
+  React Native runtime behavior.
+
+### Test Renderer versions
+
+Install the Test Renderer version that matches your React 19 minor version:
+
+| React version | Recommended Test Renderer version |
+| ------------- | --------------------------------- |
+| `19.2`        | `test-renderer@1.2`               |
+| `19.1`        | `test-renderer@1.1`               |
+| `19.0`        | `test-renderer@1.0`               |
+
+Older Test Renderer lines may not support newer React 19 features in tests. Newer Test
+Renderer lines 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.
+
+### Codemods
+
+Two codemods are available to automate the most common v14 upgrade work:
+
+- `rntl-v14-update-deps` updates dependencies by removing React Test Renderer packages,
+  adding Test Renderer, and updating React Native Testing Library.
+- `rntl-v14-async-functions` updates test code for async `render`, `renderHook`, `fireEvent`,
+  `act`, `rerender`, and `unmount` usage.
+
+### Full changelog
+
+See the full GitHub comparison:
+https://github.com/callstack/react-native-testing-library/compare/v13.3.3...v14.0.0

codemods/v14-update-deps/README.md

@@ -6,8 +6,12 @@ This codemod automatically updates your `package.json` to prepare for React Nati
 
 - Removes `@types/react-test-renderer` and `react-test-renderer` (no longer needed)
 - Moves `@testing-library/react-native` to `devDependencies` if it's in `dependencies`
-- Updates `@testing-library/react-native` to `^14.0.0-beta.0`
-- Adds `test-renderer@^1.0.0` to `devDependencies`
+- Updates `@testing-library/react-native` to `^14.0.0-0`
+- Adds `test-renderer` to `devDependencies`, using the matching React 19 compatibility line when it can infer one:
+  - React 19.0: `test-renderer@^1.0.0`
+  - React 19.1: `test-renderer@^1.1.0`
+  - React 19.2: `test-renderer@^1.2.0`
+  - Missing or ambiguous React version: `test-renderer@^1.2.0`
 
 ## Usage
 
@@ -37,8 +41,8 @@ npx codemod@latest run rntl-v14-update-deps --target ./path/to/your/project
 ```json
 {
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }
 ```
@@ -50,7 +54,7 @@ npx codemod@latest run rntl-v14-update-deps --target ./path/to/your/project
   npm install
   # or yarn install / pnpm install
   ```
-- The codemod sets the version to `^14.0.0-beta.0`. You can manually update this if needed.
+- The codemod sets the version to `^14.0.0-0`. You can manually update this if needed.
 - For monorepos, the codemod processes each `package.json` file individually.
 
 ## Next steps

codemods/v14-update-deps/scripts/codemod.ts

@@ -3,8 +3,13 @@
 import type { Transform } from 'codemod:ast-grep';
 import type JSONLang from 'codemod:ast-grep/langs/json';
 
-const RNTL_VERSION = '^14.0.0-beta.0';
-const TEST_RENDERER_VERSION = '^1.0.0';
+const RNTL_VERSION = '^14.0.0-0';
+const TEST_RENDERER_FALLBACK_VERSION = '^1.2.0';
+const TEST_RENDERER_VERSION_BY_REACT_MINOR: Record<string, string> = {
+  '19.0': '^1.0.0',
+  '19.1': '^1.1.0',
+  '19.2': '^1.2.0',
+};
 
 interface PackageJson {
   dependencies?: Record<string, string>;
@@ -141,10 +146,44 @@ function ensureRntlInDevDependencies(packageJson: PackageJson): boolean {
 }
 
 function updateTestRendererVersionInDevDependencies(packageJson: PackageJson): boolean {
+  const expectedVersion = getTestRendererVersion(packageJson);
   const currentVersion = packageJson.devDependencies?.['test-renderer'];
-  if (currentVersion !== TEST_RENDERER_VERSION) {
-    packageJson.devDependencies!['test-renderer'] = TEST_RENDERER_VERSION;
+  if (currentVersion !== expectedVersion) {
+    packageJson.devDependencies!['test-renderer'] = expectedVersion;
     return true;
   }
   return false;
 }
+
+function getTestRendererVersion(packageJson: PackageJson): string {
+  const reactVersion = getPackageVersion(packageJson, 'react');
+  const reactMinor = reactVersion ? getKnownReact19Minor(reactVersion) : null;
+
+  return reactMinor
+    ? TEST_RENDERER_VERSION_BY_REACT_MINOR[reactMinor]
+    : TEST_RENDERER_FALLBACK_VERSION;
+}
+
+function getPackageVersion(packageJson: PackageJson, pkgName: string): string | undefined {
+  for (const depType of [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+  ] as const) {
+    const version = packageJson[depType]?.[pkgName];
+    if (version) {
+      return version;
+    }
+  }
+
+  return undefined;
+}
+
+function getKnownReact19Minor(version: string): string | null {
+  const trimmedVersion = version.trim();
+  const exactVersionMatch = trimmedVersion.match(/^=?~?(19\.(?:0|1|2))(?:\.\d+)?(?:-[\w.-]+)?$/);
+  const xRangeMatch = trimmedVersion.match(/^~?(19\.(?:0|1|2))\.(?:x|\*)$/i);
+
+  return exactVersionMatch?.[1] ?? xRangeMatch?.[1] ?? null;
+}

codemods/v14-update-deps/tests/fixtures/already-alpha/expected.json

@@ -2,7 +2,7 @@
   "name": "test-project",
   "version": "1.0.0",
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }

codemods/v14-update-deps/tests/fixtures/basic-update/expected.json

@@ -2,7 +2,7 @@
   "name": "test-project",
   "version": "1.0.0",
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }

codemods/v14-update-deps/tests/fixtures/move-from-deps/expected.json

@@ -2,7 +2,7 @@
   "name": "test-project",
   "version": "1.0.0",
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }

codemods/v14-update-deps/tests/fixtures/react-19-0/expected.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "react": "19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.0.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-0/input.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@testing-library/react-native": "^13.0.0",
+    "react": "19.0.0"
+  },
+  "devDependencies": {
+    "react-test-renderer": "19.0.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-1/expected.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "react": "~19.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.1.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-1/input.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@testing-library/react-native": "^13.0.0",
+    "react": "~19.1.0"
+  },
+  "devDependencies": {
+    "react-test-renderer": "19.1.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-2/expected.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "react": "19.2.x"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-2/input.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@testing-library/react-native": "^13.0.0",
+    "react": "19.2.x"
+  },
+  "devDependencies": {
+    "react-test-renderer": "19.2.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-ambiguous-range/expected.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-19-ambiguous-range/input.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@testing-library/react-native": "^13.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "react-test-renderer": "19.0.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-non-19/expected.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "react": "^18.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/react-non-19/input.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@testing-library/react-native": "^13.0.0",
+    "react": "^18.3.0"
+  },
+  "devDependencies": {
+    "react-test-renderer": "18.3.0"
+  }
+}

codemods/v14-update-deps/tests/fixtures/rntl-in-devdeps/expected.json

@@ -1,6 +1,6 @@
 {
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }

codemods/v14-update-deps/tests/fixtures/with-peer-deps/expected.json

@@ -2,7 +2,7 @@
   "name": "test-project",
   "version": "1.0.0",
   "devDependencies": {
-    "@testing-library/react-native": "^14.0.0-beta.0",
-    "test-renderer": "^1.0.0"
+    "@testing-library/react-native": "^14.0.0-0",
+    "test-renderer": "^1.2.0"
   }
 }