api-queries.md

id	api-queries
title	Queries
sidebar_label	Queries

Variants

getBy queries are shown by default in the query documentation below.

getBy

getBy* queries returns the first matching node for a query, and throws an error if no elements match or if more than one match is found (use getAllBy instead).

getAllBy

getAllBy* queries return an array of all matching nodes for a query, and throws an error if no elements match.

queryBy

queryBy* queries returns the first matching node for a query, and return null if no elements match. This is useful for asserting an element is not present. This throws if more than one match is found (use queryAllBy instead)..

queryAllBy

queryAllBy* queries return an array of all matching nodes for a query, and return an empty array ([]) if no elements match.

findBy

findBy* queries return a promise which resolves when an element is found which matches the given query. The promise is rejected if no element is found or if more than one element is found after a default timeout of 4500ms. If you need to find more than one element, then use findAllBy.

Note, this is a simple combination of getBy* queries and waitForElement. The findBy* queries accept the waitForElement options as the last argument. (i.e. findByText(container, 'text', queryOptions, waitForElementOptions))

findAllBy

findAllBy* queries return a promise which resolves to an array of elements when any elements are found which match the given query. The promise is rejected if no elements are found after a default timeout of 4500ms.

Options

The argument to a query can be a string, regular expression, or function. There are also options to adjust how node text is parsed.

See TextMatch for documentation on what can be passed to a query.

Queries

ByHintText

getByHintText, queryByHintText, getAllByHintText, queryAllByHintText, findByHintText, findAllByHintText

getByHintText(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all elements with an accessibilityHint prop and find one that matches the given TextMatch.

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

const { getByHintText } = render(<View accessibilityHint="summary" />);

getByHintText('summary'); // returns the View node

ByLabelText

getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText findByLabelText, findAllByLabelText

getByLabelText(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all elements with an accessibilityLabel prop and find one that matches the given TextMatch.

function Login({ onPress }) {
  return (
    <View accessibilityLabel="login-form">
      <Text>Login</Text>
      <TextInput accessibilityLabel="username" />
      <TextInput accessibilityLabel="password" />
      <Button title="Login" onPress={onPress} />
    </View>
  );
}

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

const { getByLabelText } = render(<Login onPress={jest.fn()} />);

getByLabelText('username'); // returns the TextInput node

ByRole

getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole, findAllByRole

getByRole(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    selector?: SelectorFn,
  }): NativeTestInstance

This will search for all elements with an accessibilityRole prop and find one that matches the given TextMatch.

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

const { getByRole } = render(<View accessibilityRole="summary" />);

getByRole('summary'); // returns the View node

ByRole queries will fall back to searching for elements with an accessibilityTraits match, but they will log a warning on all matches that this prop is being deprecated by react-native.

ByPlaceholderText

getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText, queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText

getByPlaceholderText(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all elements with a placeholder prop and find one that matches the given TextMatch.

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

const { getByPlaceholderText } = render(<TextInput placeholder="Username" />);

getByPlaceholderText('Username'); // returns the TextInput node

ByText

getByText, queryByText, getAllByText, queryAllByText, findByText, findAllByText

getByText(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all elements of type Text with props.children matching the given. It will also search for Button elements by their title TextMatch.

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

const { getByText } = render(<Text>About ℹ</Text>);

getByText(/about/i); // returns the Text node

ByTitle

getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle, findAllByTitle

getByTitle(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all Button or RefreshControl elements with props.title matching the given by their value TextMatch.

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

const { getByTitle } = render(<Button title="About" />);

getByTitle(/about/i); // returns the Button node

ByDisplayValue

getByDisplayValue, queryByDisplayValue, getAllByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue

getByDisplayValue(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    exact?: boolean = true,
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NormalizerOptions

This will search for all TextInput elements with a value prop and Picker or Switch elements with a selectedValue prop and find ones that matches the given TextMatch.

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

const { getByDisplayValue } = render(<Input value="About ℹ" onChangeText={() => ({})} />);

getByDisplayValue(/about/i); // returns the Input node

ByTestId

getByTestId, queryByTestId, getAllByTestId, queryAllByTestId, findByTestId, findAllByTestId

getByTestId(
  container: NativeTestInstance,
  match: TextMatch,
  options?: {
    trim?: boolean = true,
    collapseWhitespace?: boolean = true,
    exact?: boolean = true,
    selector?: SelectorFn,
    normalizer?: NormalizerFn,
  }): NativeTestInstance

This will search for all elements with a testID and find one that matches the given TextMatch.

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

const { getByTestId } = render(<Text testID="test">hi there</Text>);

getByTestId('test'); // returns the Text node

Because your users can't see testIDs the guiding principles, please only use this as a last resort. Users don't interact with testIDs, and can lead to unpredictable behavior. For example, internal React Native components sometimes spread testIds down to child components. This means that if you query all by testId, you may get significantly more results than you anticipate which will lead to unpredictable tests.

TextMatch

Several APIs accept a TextMatch which can be a string, regex or a function which returns true for a match and false for a mismatch.

Precision

Some APIs accept an object as the final argument that can contain options that affect the precision of string matching:

• exact: Defaults to true; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive.
  • exact has no effect on regex or function arguments.
  • In most cases using a regex instead of a string gives you more control over fuzzy matching and should be preferred over { exact: false }.
• normalizer: An optional function which overrides normalization behavior. See Normalization.

Normalization

Before running any matching logic against text, it is automatically normalized. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.

If you want to prevent that normalization, or provide alternative normalization (e.g. to remove Unicode control characters), you can provide a normalizer function in the options object. This function will be given a string and is expected to return a normalized version of that string.

Note: Specifying a value for normalizer replaces the built-in normalization, but you can call getDefaultNormalizer to obtain a built-in normalizer, either to adjust that normalization or to call it from your own normalizer.

getDefaultNormalizer takes an options object which allows the selection of behaviour:

• trim: Defaults to true. Trims leading and trailing whitespace
• collapseWhitespace: Defaults to true. Collapses inner whitespace (newlines, tabs, repeated spaces) into a single space.

Normalization Examples

To perform a match against text without trimming:

getByText(node, 'text', {
  normalizer: getDefaultNormalizer({ trim: false }),
});

To override normalization to remove some Unicode characters whilst keeping some (but not all) of the built-in normalization behavior:

getByText(node, 'text', {
  normalizer: (str) => getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
});

TextMatch Examples

Given the following render:

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

Will find a match:

// Matching a string:
getByText(baseElement, 'Hello World'); // full string match
getByText(baseElement, 'llo Worl', { exact: false }); // substring match
getByText(baseElement, 'hello world', { exact: false }); // ignore case

// Matching a regex:
getByText(baseElement, /World/); // substring match
getByText(baseElement, /world/i); // substring match, ignore case
getByText(baseElement, /^hello world$/i); // full string match, ignore case
getByText(baseElement, /Hello W?oRlD/i); // advanced regex

// Matching with a custom function:
getByText(baseElement, (content) => content.startsWith('Hello'));

Will not find a match:

// full string does not match
getByText(testElement, 'Goodbye World');

// case-sensitive regex with different case
getByText(testElement, /hello world/);