# React Native Testing Library

> Helps you to write better tests with less effort.

## Docs

- [Testing environment](/react-native-testing-library/docs/advanced/testing-env.md): :::info This document is intended for a more advanced audience who want to understand the internals of our testing environment better, e.g., to contribute to the codebase. You should be able to write integration or component tests without reading this. ::: React Native Testing Library allows you to write integration and component tests for your React Native app or library. While the JSX code used in tests closely resembles your React Native app, things aren't as simple as they might appear. This document describes the key elements of our testing environment and highlights things to be aware of when writing more advanced tests or diagnosing issues.
- [Third-Party Library Integration](/react-native-testing-library/docs/advanced/third-party-integration.md): The React Native Testing Library is designed to simulate the core behaviors of React Native. However, it doesn't replicate the internal logic of third-party libraries. This guide explains how to integrate your library with RNTL.
- [Understanding `act` function](/react-native-testing-library/docs/advanced/understanding-act.md): When writing RNTL tests, one of the things that confuses developers the most are cryptic act() function errors logged to the console. This article explains the purpose and behavior of act() so you can write tests with more confidence.
- [API Overview](/react-native-testing-library/docs/api.md): React Native Testing Library consists of following APIs: render function - render your UI components for testing purposesscreen object - access rendered UI:Queries - find relevant components by various predicates: role, text, test ids, etcLifecycle methods: rerender, unmountHelpers: debug, toJSON, rootJest matchers - validate assumptions about your UIUser Event - simulate common user interactions like press or type in a realistic wayFire Event - simulate any component event in a simplified way purposesMisc APIs:renderHook function - render hooks for testingAsync utils: findBy* queries, wait, waitForElementToBeRemovedConfiguration: configure, resetToDefaultsAccessibility: isHiddenFromAccessibilityOther: within, act, cleanup
- [Fire Event API](/react-native-testing-library/docs/api/events/fire-event.md)
- [User Event interactions](/react-native-testing-library/docs/api/events/user-event.md)
- [Jest matchers](/react-native-testing-library/docs/api/jest-matchers.md): This guide describes built-in Jest matchers. These matchers provide readable assertions with accessibility support.
- [Accessibility](/react-native-testing-library/docs/api/misc/accessibility.md)
- [Async utilities](/react-native-testing-library/docs/api/misc/async.md)
- [Configuration](/react-native-testing-library/docs/api/misc/config.md)
- [Other helpers](/react-native-testing-library/docs/api/misc/other.md)
- [`renderHook` function](/react-native-testing-library/docs/api/misc/render-hook.md)
- [Queries](/react-native-testing-library/docs/api/queries.md): Queries are one of the main building blocks of React Native Testing Library. They let you find elements in the element tree, which represents your application's user interface when running under tests.
- [`render` API](/react-native-testing-library/docs/api/render.md)
- [`screen` object](/react-native-testing-library/docs/api/screen.md): The screen object offers a recommended way to access queries and utilities for the currently rendered UI. This object is assigned after the render call and cleared after each test by calling 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 most important feature of screen is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. See Queries for a complete list. Example rerender Also available under update alias Re-renders 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 is updated; otherwise, it re-mounts a new tree. In both cases, it triggers the appropriate lifecycle events. rerenderAsync Also available under updateAsync alias :::info RNTL minimal version
This API requires RNTL v13.3.0 or later.
::: Async version of rerender designed for working with React 19 and React Suspense. This method uses async act internally to ensure all pending React updates are executed during updating. unmount Unmount the in-memory tree, triggering the appropriate lifecycle events. :::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). ::: unmountAsync :::info RNTL minimal version
This API requires RNTL v13.3.0 or later.
::: Async version of unmount designed for working with React 19 and React Suspense. This method uses async act internally to ensure all pending React updates are executed during unmounting. :::note
Usually you should not need to call unmountAsync as it is done automatically if your test runner supports afterEach hook (like Jest, mocha, Jasmine).
::: debug Pretty prints deeply rendered component passed to render. message option {#debug-message-option} You can provide a message that will be printed on top. logs optional message and colored JSX: mapProps option {#debug-map-props-option} You can use the mapProps option to transform the props that will be printed: 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 to make them more readable (e.g., flatten styles). Or remove props that have little value when debugging tests, e.g., path prop for SVGs toJSON Get the rendered component JSON representation, e.g. for snapshot testing. root Returns the rendered root host element. This API is primarily useful for component tests, as it allows you to access the root host view without using *ByTestId queries or similar methods. UNSAFE_root :::caution
This API typically will return a composite view, which goes against recommended testing practices. This API is primarily available for legacy test suites that rely on such testing.
::: Returns the rendered composite root element. :::note
This API was previously named container for compatibility with React Testing Library. However, despite the same name, the actual behavior was significantly different, so we changed the name to UNSAFE_root.
:::
- [Common Mistakes with React Native Testing Library](/react-native-testing-library/docs/guides/common-mistakes.md): Note: This guide is adapted from Kent C. Dodds' article "Common mistakes with React Testing Library" for React Native Testing Library v13. The original article focuses on web React, but the principles apply to React Native as well. This adaptation includes React Native-specific examples and ARIA-compatible accessibility attributes. React Native Testing Library guiding principle is: "The more your tests resemble the way your software is used, the more confidence they can give you." This guide outlines some common mistakes people make when using React Native Testing Library and how to avoid them.
- [Community resources](/react-native-testing-library/docs/guides/community-resources.md)
- [FAQ](/react-native-testing-library/docs/guides/faq.md)
- [How should I query?](/react-native-testing-library/docs/guides/how-to-query.md): React Native Testing Library provides various query types for finding views in your tests. The number of queries might be confusing. This guide helps you pick the right queries for your test scenarios.
- [LLM Guidelines for React Native Testing Library](/react-native-testing-library/docs/guides/llm-guidelines.md): Actionable guidelines for writing tests with React Native Testing Library (RNTL) v13.
- [React 19 & Suspense Support](/react-native-testing-library/docs/guides/react-19.md): React 19 introduced full support for React Suspense, React.use(), and other async rendering features to React Native 0.78.0. When testing components that use these features, React requires the async act helper to handle async state updates. This means React Native Testing Library needs new async versions of its core APIs. These async APIs work with both React 18 and React 19.
- [Troubleshooting](/react-native-testing-library/docs/guides/troubleshooting.md): This guide describes common issues found by users when integrating React Native Test Library to their projects:
- [Migration to built-in Jest matchers](/react-native-testing-library/docs/migration/jest-matchers.md): This guide describes the steps necessary to migrate from legacy Jest Native matchers v5 to built-in Jest matchers.
- [Migration to 11.x](/react-native-testing-library/docs/migration/previous/v11.md): Migration to React Native Testing Library version 11 from version 9.x or 10.x should be a relatively easy task due small amount of breaking changes.
- [Migration to 12.x](/react-native-testing-library/docs/migration/previous/v12.md): :::info If you are already using legacy @testing-library/jest-native Jest Matchers, we have a migration guide for moving to the built-in matchers. ::: React Native Testing Library 12 introduces a handful of breaking changes compared to 11.x versions. We believe they were necessary to improve the experience using the library and help the users fall into the pit of success when writing meaningful tests. You will find migration instructions for each and every change described below.
- [Migration to 2.x](/react-native-testing-library/docs/migration/previous/v2.md): This guide describes steps necessary to migrate from React Native Testing Library v1.x to v2.x.
- [Migration to 7.x](/react-native-testing-library/docs/migration/previous/v7.md): :::info We renamed the react-native-testing-library npm package to @testing-library/react-native, officially joining the "Testing Library" family 🎉. ::: As the version 7.0 involves merging two libraries together, there are two variants for migration guide, dependent on library you used previously:
- [Migration to 9.x](/react-native-testing-library/docs/migration/previous/v9.md): Version 7.0 brought React Native Testing Library into the @testing-library family. Since it has been implemented independently from its web counterpart – the React Testing Library – there are some differences in the API and behavior. Version 9.0 solves several of these problems.
- [Migration to 13.x](/react-native-testing-library/docs/migration/v13.md): This guide describes the migration to React Native Testing Library version 13 from version 12.x. Overall, the v13 release is relatively small, focusing on removing deprecated queries and improving the developer experience.
- [Introduction](/react-native-testing-library/docs/start/intro.md)
- [Quick Start](/react-native-testing-library/docs/start/quick-start.md)

## Cookbook

- [Network Requests](/react-native-testing-library/cookbook/advanced/network-requests.md)
- [Async tests](/react-native-testing-library/cookbook/basics/async-tests.md)
- [Custom `render` function](/react-native-testing-library/cookbook/basics/custom-render.md): Summary RNTL exposes the render function as the primary entry point for tests. If you make complex, repeating setups for your tests, consider creating a custom render function. The idea is to encapsulate common setup steps and test wiring inside a render function suitable for your tests. Example Example full source code. More info Additional params A custom render function might accept additional parameters to allow for setting up different start conditions for a test, e.g., the initial state for global state management. Multiple functions Depending on the situation, you may declare more than one custom render function. For example, you have one function for testing application flows and a second for testing individual screens. Async function Make it async if you want to put some async setup in your custom render function.
- [Introduction](/react-native-testing-library/cookbook/index.md): Welcome to the React Native Testing Library (RNTL) Cookbook!
This app is your go-to resource for learning how to effectively test React Native applications.
It provides a collection of best practices, ready-made recipes, and tips & tricks to
simplify and improve your testing workflow. Whether you’re a beginner just getting started or a
seasoned developer looking to sharpen your
skills, the Cookbook has something for everyone.
- [Jotai](/react-native-testing-library/cookbook/state-management/jotai.md)

## Others

- [](/react-native-testing-library/404.md)