#Queries

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.

#Accessing queries

All queries described below are accessible in two main ways: through the screen object or by capturing the result of the render function call.

#Using screen object

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

test('accessing queries using "screen" object', () => {
  render(...);

  screen.getByRole("button", { name: "Start" });
})

The recommended way to access queries is to use the screen object exported by @testing-library/react-native. It contains methods for all available queries bound to the most recently rendered UI.

#Using render result

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

test('accessing queries using "render" result', () => {
  const { getByRole } = render(...);
  getByRole("button", { name: "Start" });
})

The classic way is to capture query functions returned from the render function call. This provides access to the same functions as the screen object.

#Query parts

Each query is composed of two parts: variant and predicate, separated by the word by in the middle.

Consider the query getByRole():

• getBy* is the query variant
• *ByRole is the predicate

#Query variant

The query variants describe the expected number (and timing) of matching elements, so they differ in return type.

Queries work as implicit assertions on the number of matching elements and throw an error when the assertion fails.

#getBy* queries

getByX(...): ReactTestInstance

getBy* queries return the single matching element for a query and throw an error if no elements match or if more than one match is found. If you need to find more than one element, use getAllBy.

#getAllBy* queries

getAllByX(...): ReactTestInstance[]

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

#queryBy* queries

queryByX(...): ReactTestInstance | null

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

#queryAllBy* queries

queryAllByX(...): ReactTestInstance[]

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

#findBy* queries

findByX(
  ...,
  waitForOptions?: {
    timeout?: number,
    interval?: number,
  },
): Promise<ReactTestInstance>

findBy* queries return a promise that resolves when a matching element is found. The promise is rejected if no elements match or if more than one match is found after a default timeout of 1000 ms. If you need to find more than one element, use findAllBy* queries.

#findAllBy* queries

findAllByX(
  ...,
  waitForOptions?: {
    timeout?: number,
    interval?: number,
  },
): Promise<ReactTestInstance[]>

findAllBy* queries return a promise that resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms.

#Query predicates

Note: most methods like this one return a ReactTestInstance with the following properties that you may be interested in:

type ReactTestInstance = {
  type: string | Function;
  props: { [propName: string]: any };
  parent: ReactTestInstance | null;
  children: Array<ReactTestInstance | string>;
};

#*ByRole

getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole

getByRole(
  role: TextMatch,
  options?: {
    name?: TextMatch
    disabled?: boolean,
    selected?: boolean,
    checked?: boolean | 'mixed',
    busy?: boolean,
    expanded?: boolean,
    value: {
      min?: number;
      max?: number;
      now?: number;
      text?: TextMatch;
    },
    includeHiddenElements?: boolean;
  }
): ReactTestInstance;

Returns a ReactTestInstance with matching role or accessibilityRole prop.

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

render(
  <Pressable accessibilityRole="button" disabled>
    <Text>Hello</Text>
  </Pressable>
);
const element = screen.getByRole('button');
const element2 = screen.getByRole('button', { name: 'Hello' });
const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });

#Options

• name: Finds an element with the given role/accessibilityRole and an accessible name (= accessibility label or text content).

• disabled: You can filter elements by their disabled state (coming either from aria-disabled prop or accessibilityState.disabled prop). The possible values are true or false. Querying disabled: false will also match elements with disabled: undefined (see the wiki for more details).

  • See React Native's accessibilityState docs to learn more about the disabled state.
  • This option can alternatively be expressed using the toBeEnabled() / toBeDisabled() Jest matchers.

• selected: You can filter elements by their selected state (coming either from aria-selected prop or accessibilityState.selected prop). The possible values are true or false. Querying selected: false will also match elements with selected: undefined (see the wiki for more details).

  • See React Native's accessibilityState docs to learn more about the selected state.
  • This option can alternatively be expressed using the toBeSelected() Jest matcher.

• checked: You can filter elements by their checked state (coming either from aria-checked prop or accessibilityState.checked prop). The possible values are true, false, or "mixed".

  • See React Native's accessibilityState docs to learn more about the checked state.
  • This option can alternatively be expressed using the toBeChecked() / toBePartiallyChecked() Jest matchers.

• busy: You can filter elements by their busy state (coming either from aria-busy prop or accessibilityState.busy prop). The possible values are true or false. Querying busy: false will also match elements with busy: undefined (see the wiki for more details).

  • See React Native's accessibilityState docs to learn more about the busy state.
  • This option can alternatively be expressed using the toBeBusy() Jest matcher.

• expanded: You can filter elements by their expanded state (coming either from aria-expanded prop or accessibilityState.expanded prop). The possible values are true or false.

  • See React Native's accessibilityState docs to learn more about the expanded state.
  • This option can alternatively be expressed using the toBeExpanded() / toBeCollapsed() Jest matchers.

• value: Filter elements by their accessibility value, based on either aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, or accessibilityValue props. Accessibility value conceptually consists of numeric min, max, and now entries, as well as string text entry.

  • See React Native accessibilityValue docs to learn more about the accessibility value concept.
  • This option can alternatively be expressed using the toHaveAccessibilityValue() Jest matcher.

#*ByLabelText

getByLabelText, getAllByLabelText, queryByLabelText, queryAllByLabelText, findByLabelText, findAllByLabelText

getByLabelText(
  text: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  },
): ReactTestInstance;

Returns a ReactTestInstance with matching label:

• either by matching aria-label/accessibilityLabel prop
• or by matching the text content of the view referenced by aria-labelledby/accessibilityLabelledBy prop

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

render(<MyComponent />);
const element = screen.getByLabelText('my-label');

#*ByPlaceholderText

getByPlaceholderText, getAllByPlaceholderText, queryByPlaceholderText, queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText

getByPlaceholderText(
  text: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  }
): ReactTestInstance;

Returns a ReactTestInstance for a TextInput with a matching placeholder—may be a string or regular expression.

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

render(<MyComponent />);
const element = screen.getByPlaceholderText('username');

#*ByDisplayValue

getByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue

getByDisplayValue(
  value: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  },
): ReactTestInstance;

Returns a ReactTestInstance for a TextInput with a matching display value. The value can be a string or regular expression.

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

render(<MyComponent />);
const element = screen.getByDisplayValue('username');

#*ByText

getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText

getByText(
  text: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  }
): ReactTestInstance;

Returns a ReactTestInstance with matching text. The text can be a string or regular expression.

This method joins <Text> siblings to find matches, similarly to how React Native handles these components. This allows querying for strings that will be visually rendered together but may be semantically separate React components.

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

render(<MyComponent />);
const element = screen.getByText('banana');

#*ByHintText

getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint, findByAccessibilityHint, findAllByAccessibilityHint getByHintText, getAllByHintText, queryByHintText, queryAllByHintText, findByHintText, findAllByHintText

getByHintText(
  hint: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  },
): ReactTestInstance;

Returns a ReactTestInstance with matching accessibilityHint prop.

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

render(<MyComponent />);
const element = screen.getByHintText('Plays a song');

#*ByTestId

getByTestId, getAllByTestId, queryByTestId, queryAllByTestId, findByTestId, findAllByTestId

getByTestId(
  testId: TextMatch,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
    includeHiddenElements?: boolean;
  },
): ReactTestInstance;

Returns a ReactTestInstance with a matching testID prop. testID may be a string or a regular expression.

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

render(<MyComponent />);
const element = screen.getByTestId('unique-id');

#Common options

Usually the query's first argument can be a string or a regex. All queries take at least the hidden option as an optional second argument, and some queries accept more options that change string matching behavior. See TextMatch for more info.

#includeHiddenElements option

All queries have the includeHiddenElements option which affects whether elements hidden from accessibility are matched by the query. By default, queries won't match hidden elements because users of the app wouldn't be able to see such elements.

You can configure the default value with the configure function.

This option is also available as hidden alias for compatibility with React Testing Library.

Examples

render(<Text style={{ display: 'none' }}>Hidden from accessibility</Text>);

// Exclude hidden elements
expect(
  screen.queryByText('Hidden from accessibility', {
    includeHiddenElements: false,
  })
).not.toBeOnTheScreen();

// Include hidden elements
expect(screen.getByText('Hidden from accessibility')).toBeOnTheScreen();
expect(
  screen.getByText('Hidden from accessibility', { includeHiddenElements: true })
).toBeOnTheScreen();

#TextMatch type

type TextMatch = string | RegExp;

Most query APIs take a TextMatch as an argument, which means the argument can be either a string or regex.

#Examples

Given the following render:

render(<Text>Hello World</Text>);

Will find a match:

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

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

Will NOT find a match

// substring does not match
screen.getByText('llo Worl');
// full string does not match
screen.getByText('Goodbye World');

// case-sensitive regex with different case
screen.getByText(/hello world/);

#Options

#Precision

type TextMatchOptions = {
  exact?: boolean;
  normalizer?: (text: string) => string;
};

Queries that take a TextMatch also accept an object as the second argument that contains options affecting 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 argument.
  • 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.

The exact option defaults to true, but if you want to search for a text slice or make text matching case-insensitive, you can override it. That said, we advise you to use regex in more complex scenarios.

#Normalization

Before running any matching logic against text, it's 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 is given a string and is expected to return a normalized version of that string.

getDefaultNormalizer takes an options object that allows selection of behavior:

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

screen.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:

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

#Legacy unit testing helpers

render from @testing-library/react-native exposes additional queries that should not be used in integration or component testing, but some users (like component library creators) interested in unit testing some components may find helpful.

The interface is the same as for other queries, but we won't provide full names so they're harder to find via search engines.

#UNSAFE_ByType

UNSAFE_getByType, UNSAFE_getAllByType, UNSAFE_queryByType, UNSAFE_queryAllByType

Returns a ReactTestInstance with a matching React component type.

#UNSAFE_ByProps

UNSAFE_getByProps, UNSAFE_getAllByProps, UNSAFE_queryByProps, UNSAFE_queryAllByProps

Returns a ReactTestInstance with matching props.