You are viewing documentation for v14 alpha. This version is under active development and APIs may change.
  • 14.x

      • Migration to 14.x

      Alpha Version

      This version is currently in alpha. APIs and behavior may change before the stable release. Please report any issues you encounter.

      This guide describes the migration to React Native Testing Library version 14 from version 13.x.

      Overview

      RNTL v14 is a major release that drops support for React 18 and fully embraces React 19's async-first paradigm. Key changes include:

      • React 19+ required: Minimum supported versions are React 19.0.0 and React Native 0.78+
      • Async APIs by default: render, renderHook, fireEvent, and act are now async
      • New renderer: Switched from deprecated React Test Renderer to Test Renderer
      • API cleanup: Removed deprecated APIs (update, getQueriesForElement, UNSAFE_root, concurrentRoot option)
      • Safe container API: Reintroduced container which is now safe to use
      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

      npm
      yarn
      pnpm
      bun
      npx codemod@latest rntl-v14-update-deps --target .
npm install

      Step 2: Update test code to async

      npm
      yarn
      pnpm
      bun
      npx codemod@latest rntl-v14-async-functions --target ./src

      After running the codemods, review the changes and run your tests.

      Breaking Changes

      Supported React and React Native versions

      This version requires React 19+ and React Native 0.78+. If you need to support React 18, please use the latest v13.x version.

      RNTL VersionReact VersionReact Native Version
      v14.x>= 19.0.0>= 0.78
      v13.x>= 18.0.0>= 0.71

      Test Renderer replaces React Test Renderer

      In v14, React Native Testing Library now uses Test Renderer instead of the deprecated React Test Renderer. Test Renderer is a modern, actively maintained alternative that provides better compatibility with React 19 and improved type safety.

      What changed:

      • The underlying renderer has been switched from React Test Renderer to Test Renderer
      • This change is mostly internal and should not require code changes in most cases
      • Type definitions have been updated to use HostElement from Test Renderer instead of ReactTestInstance

      Migration:

      1. Update dependencies

      Run codemod for updating dependencies:

      npm
      yarn
      pnpm
      bun
      npx codemod@latest rntl-v14-update-deps
npm install
      Manual changes

      Remove React Test Renderer and its type definitions from your dev dependencies, and add Test Renderer:

      npm
      yarn
      pnpm
      bun
      npm uninstall react-test-renderer @types/react-test-renderer
npm install -D test-renderer

      2. Update type imports (if needed)

      If you were directly importing types from React Test Renderer, you may need to update your imports:

      // Before (v13)
import type { ReactTestInstance } from 'react-test-renderer';

// After (v14)
import type { HostElement } from 'test-renderer';

      Note: Most users won't need to update type imports, as React Native Testing Library now exports the necessary types directly.

      For more details, see the Test Renderer documentation.

      Async APIs by Default

      With React 18 support dropped, RNTL v14 fully embraces 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>
      Already using async APIs?

      If you adopted the async APIs introduced in RNTL v13.3 (renderAsync, fireEventAsync, renderHookAsync), simply rename them to their non-async counterparts (render, fireEvent, renderHook). The async versions have been removed as the standard APIs are now async by default.

      render is now async

      In v14, render is now async by default and returns a Promise. This change enables proper support for async React features like Suspense boundary or use() hook.

      Before (v13):

      import { render, screen } from '@testing-library/react-native';

it('should render component', () => {
  render(<MyComponent />);
  expect(screen.getByText('Hello')).toBeOnTheScreen();
});

      After (v14):

      import { render, screen } from '@testing-library/react-native';

it('should render component', async () => {
  await render(<MyComponent />);
  expect(screen.getByText('Hello')).toBeOnTheScreen();
});

      For more details, see the render API documentation.

      renderHook is now async

      In v14, renderHook is now async by default and returns a Promise.

      Before (v13):

      import { renderHook } from '@testing-library/react-native';

it('should test hook', () => {
  const { result, rerender } = renderHook(() => useMyHook());

  rerender(newProps);
  unmount();
});

      After (v14):

      import { renderHook } from '@testing-library/react-native';

it('should test hook', async () => {
  const { result, rerender } = await renderHook(() => useMyHook());

  await rerender(newProps);
  await unmount();
});

      For more details, see the renderHook API documentation.

      fireEvent is now async

      In v14, fireEvent and its helpers (press, changeText, scroll) are now async by default and return a Promise.

      Before (v13):

      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):

      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();
});

      act is now async

      In v14, act is now async by default and always returns a Promise. You should always await the result of act().

      What changed:

      • act now always returns a Promise<T> instead of T | Thenable<T>
      • act should always be awaited
      • The API is more consistent and predictable
      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):

      import { act } from '@testing-library/react-native';

it('should update state', () => {
  act(() => {
    setState('new value');
  });
  expect(state).toBe('new value');
});

      After (v14):

      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.

      For more details, see the act API documentation.

      Benefits of Async APIs

      • Suspense support: Properly handles Suspense boundaries and use() hook
      • Better timing: Ensures all pending React updates are executed before assertions
      • Simpler mental model: All rendering operations are consistently async
      • Future-proof: Aligns with React's direction toward async rendering

      Removed APIs

      update alias removed

      The update alias for rerender has been removed. Use rerender instead:

      // 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:

      // 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:

      // 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 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.

      // 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 by default, as it is the standard rendering mode for React 19 and React Native's New Architecture.

      // 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: Simply remove any concurrentRoot options from your render calls and configure function. If you were explicitly setting concurrentRoot: true, no changes are needed beyond removing the option. If you were setting concurrentRoot: false to disable concurrent rendering, this is no longer supported in v14.

      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. In v14, container now returns a pseudo-element container whose children are the elements you asked to render, making it safe and 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):

      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):

      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;
});

      For more details, see the screen API documentation.

      Text string validation enforced by default

      In v14, Test Renderer automatically enforces React Native's requirement that text strings must be rendered within a <Text> component. This means the unstable_validateStringsRenderedWithinText option has been removed from RenderOptions, as this validation is now always enabled.

      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:

      // 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.

      Codemods

      We provide two codemods to automate the migration. Both codemods are safe to run multiple times - they will 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)
      • Updates @testing-library/react-native to alpha version
      npm
      yarn
      pnpm
      bun
      npx codemod@latest rntl-v14-update-deps --target .
npm 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
      npm
      yarn
      pnpm
      bun
      npx 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:

      npm
      yarn
      pnpm
      bun
      npx codemod@latest rntl-v14-async-functions \
  --target ./src \
  --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

      Need React or React Native expertise you can count on?

      Let's talk