# React Native Testing Library

> Helps you to write better tests with less effort.

## Others

- [Network Requests](/react-native-testing-library/12.x/cookbook/advanced/network-requests.md)
- [Async tests](/react-native-testing-library/12.x/cookbook/basics/async-tests.md)
- [Custom `render` function](/react-native-testing-library/12.x/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/12.x/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/12.x/cookbook/state-management/jotai.md)
- [Testing environment](/react-native-testing-library/12.x/docs/advanced/testing-env.md): 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 are not as simple as they might appear. This document will describe the key elements of our testing environment and highlight things to be aware of when writing more advanced tests or diagnosing issues.
- [Understanding `act` function](/react-native-testing-library/12.x/docs/advanced/understanding-act.md): When writing RNTL tests one of the things that confuses developers the most are cryptic act() function errors logged into console. In this article I will try to build an understanding of the purpose and behaviour of act() so you can build your tests with more confidence.
- [API Overview](/react-native-testing-library/12.x/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/12.x/docs/api/events/fire-event.md): The fireEvent API allows you to trigger all kinds of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named onXxx when xxx is the name of the event passed. Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object. An example using fireEvent with native events that aren't already aliased by the fireEvent api. FireEvent exposes convenience methods for common events like: press, changeText, scroll. fireEvent.press {#press} Invokes press event handler on the element or parent element in the tree. fireEvent.changeText {#change-text} Invokes changeText event handler on the element or parent element in the tree. fireEvent.scroll {#scroll} Invokes scroll event handler on the element or parent element in the tree. On a ScrollView
- [User Event interactions](/react-native-testing-library/12.x/docs/api/events/user-event.md)
- [Jest matchers](/react-native-testing-library/12.x/docs/api/jest-matchers.md): This guide describes built-in Jest matchers, we recommend using these matchers as they provide readable tests, accessibility support, and a better developer experience.
- [Accessibility](/react-native-testing-library/12.x/docs/api/misc/accessibility.md)
- [Async utilities](/react-native-testing-library/12.x/docs/api/misc/async.md)
- [Configuration](/react-native-testing-library/12.x/docs/api/misc/config.md)
- [Other helpers](/react-native-testing-library/12.x/docs/api/misc/other.md)
- [`renderHook` function](/react-native-testing-library/12.x/docs/api/misc/render-hook.md): Renders a test component that will call the provided callback, including any hooks it calls, every time it renders. Returns RenderHookResult object, which you can interact with. The renderHook function accepts the following arguments: Callback is a function that is called each render of the test component. This function should call one or more hooks for testing. The props passed into the callback will be the initialProps provided in the options to renderHook, unless new props are provided by a subsequent rerender call.
- [Queries](/react-native-testing-library/12.x/docs/api/queries.md): Queries are one of the main building blocks for the React Native Testing Library. They enable you to find relevant elements in the element tree, which represents your application's user interface when running under tests.
- [`render` function](/react-native-testing-library/12.x/docs/api/render.md): The render function is the entry point for writing React Native Testing Library tests. It deeply renders the given React element and returns helpers to query the output components' structure. When using React context providers, like Redux Provider, you'll likely want to wrap rendered component with them. In such cases, it's convenient to create your own custom render method. Follow this great guide on how to set this up. Options {#render-options} The behavior of the render method can be customized by passing various options as a second argument of the RenderOptions type: wrapper option This option allows you to wrap the tested component, passed as the first option to the render() function, in an additional wrapper component. This is useful for creating reusable custom render functions for common React Context providers. concurrentRoot option {#concurrent-root} Set to true to enable concurrent rendering used in the React Native New Architecture. Otherwise render will default to legacy synchronous rendering. createNodeMock option This option allows you to pass createNodeMock option to ReactTestRenderer.create() method in order to allow for custom mock refs. You can learn more about this option from React Test Renderer documentation. unstable_validateStringsRenderedWithinText option This experimental option allows you to replicate React Native behavior of throwing Invariant Violation: Text strings must be rendered within a <Text> component error when you try to render string value under components different than <Text>, e.g., under <View>. React Test Renderer does not enforce this check; hence, by default, React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. Result {#render-result} The render function returns the same queries and utilities as the screen object. We recommended using the screen object as more developer-friendly way. See this article from Kent C. Dodds for more details.
- [`screen` object](/react-native-testing-library/12.x/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-render 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 will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events. unmount Unmount the in-memory tree, triggering the appropriate lifecycle events. 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 so that they are 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 root host view without using *ByTestId queries or similar methods. UNSAFE_root Returns the rendered composite root element.
- [Community resources](/react-native-testing-library/12.x/docs/guides/community-resources.md)
- [FAQ](/react-native-testing-library/12.x/docs/guides/faq.md)
- [How should I query?](/react-native-testing-library/12.x/docs/guides/how-to-query.md): React Native Testing Library provides various query types, allowing great flexibility in finding views appropriate for your tests. At the same time, the number of queries might be confusing. This guide aims to help you pick the correct queries for your test scenarios.
- [Troubleshooting](/react-native-testing-library/12.x/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/12.x/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/12.x/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 2.x](/react-native-testing-library/12.x/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/12.x/docs/migration/previous/v7.md): 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/12.x/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 12.x](/react-native-testing-library/12.x/docs/migration/v12.md): 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.
- [Introduction](/react-native-testing-library/12.x/docs/start/intro.md)
- [Quick Start](/react-native-testing-library/12.x/docs/start/quick-start.md)
- [](/react-native-testing-library/12.x/index.md)