Migration to 9.x#

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.

Support for text match options a.k.a string precision API#

This is a backward compatible change.

When querying text, it is now possible to pass a TextMatch to most text based queries, which lets you configure how @testing-library/react-native should match your text. For instance, passing exact: false will allow matching substrings and will ignore case:

const { getByText } = render(<Text>Hello World</Text>);

getByText('Hello World'); // Matches
getByText('Hello'); // Doesn't match
getByText('hello', { exact: false }); // ignore case-sensitivity and does partial matching

Please note that the findBy* queries used to take a waitForOptions parameter as a second argument, which has now been moved to the third argument:

-findByText('Hello world', { timeout: 3000 }); // old findBy* API
+findByText('Hello world', {}, { timeout: 3000 }); // new findBy* API

For backward compatibility RNTL v9 can still read waitForOptions from the second argument but will print a deprecation warning.

Reverted matching text across several nodes#

In v1.14 we've introduced a feature allowing to match text when it's spread across several nodes:

const { getByText } = render(
  <Text>
    Hello <Text>world</Text>
  </Text>
);
getByText('Hello world'); // matches

However this behavior was different than the web one, and wouldn't always be straightforward to reason about. For instance it could match text nodes far from each other on the screen. It also prevented us from implementing the string precision API. From v9, this type of match will not work.

A work around is to use within:

import { Text } from 'react-native'
import { render, within } from '@testing-library/react-native'

const { getByText } = render(<Text>Hello <Text>world</Text</Text>)

within(getByText('Hello', {exact: false})).getByText('world')

Future plans#

This release changes a lot of internal logic in the library, paving the way for more improvements to bring us closer to our web counterpart, with a possibly better story for accessibility queries.

We're also migrating the codebase to TypeScript. Please let us know if you're interested in helping us with this effort.

Stay safe!