#Jest matchers

This guide describes built-in Jest matchers. These matchers provide readable assertions with accessibility support.

#Setup

No setup needed. Matchers are available when you import from @testing-library/react-native.

#Migration from legacy Jest Native matchers

If you use legacy Jest Native matchers, see the migration guide.

#Checking element existence

#toBeOnTheScreen()

expect(element).toBeOnTheScreen();

Checks if an element is attached to the element tree. If a referenced element gets unmounted during the test, this assertion fails.

#Element Content

#toHaveTextContent()

expect(element).toHaveTextContent(
  text: string | RegExp,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
  },
)

Checks if the element has the specified text content. Accepts string or RegExp, with optional text match options exact and normalizer.

#toContainElement()

expect(container).toContainElement(
  element: ReactTestInstance | null,
)

Checks if a container element contains another element.

#toBeEmptyElement()

expect(element).toBeEmptyElement();

Checks if the element has no child elements or text content.

#Checking element state

#toHaveDisplayValue()

expect(element).toHaveDisplayValue(
  value: string | RegExp,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
  },
)

Checks if a TextInput has the specified display value. Accepts string or RegExp, with optional text match options exact and normalizer.

#toHaveAccessibilityValue()

expect(element).toHaveAccessibilityValue(
  value: {
    min?: number;
    max?: number;
    now?: number;
    text?: string | RegExp;
  },
)

Checks if the element has a specified accessible value.

Reads from aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, and accessibilityValue props. Only the values you specify are checked, so the element can have other accessibility value entries and still match.

For the text entry, you can use string or RegExp.

#toBeEnabled() / toBeDisabled

expect(element).toBeEnabled();
expect(element).toBeDisabled();

Checks if the element is enabled or disabled based on aria-disabled or accessibilityState.disabled props. An element is disabled when it or any ancestor is disabled.

#toBeSelected()

expect(element).toBeSelected();

Checks if the element is selected based on aria-selected or accessibilityState.selected props.

#toBeChecked() / toBePartiallyChecked()

expect(element).toBeChecked();
expect(element).toBePartiallyChecked();

Checks if the element is checked or partially checked based on aria-checked or accessibilityState.checked props.

#toBeExpanded() / toBeCollapsed()

expect(element).toBeExpanded();
expect(element).toBeCollapsed();

Checks if the element is expanded or collapsed based on aria-expanded or accessibilityState.expanded props.

#toBeBusy()

expect(element).toBeBusy();

Checks if the element is busy based on aria-busy or accessibilityState.busy props.

#Checking element style

#toBeVisible()

expect(element).toBeVisible();

Checks if the element is visible.

An element is invisible when it or any ancestor has display: none or opacity: 0 styles, or when it's hidden from accessibility.

#toHaveStyle()

expect(element).toHaveStyle(
  style: StyleProp<Style>,
)

Checks if the element has specific styles.

#Other matchers

#toHaveAccessibleName()

expect(element).toHaveAccessibleName(
  name?: string | RegExp,
  options?: {
    exact?: boolean;
    normalizer?: (text: string) => string;
  },
)

Checks if the element has the specified accessible name. Accepts string or RegExp, with optional text match options exact and normalizer.

The accessible name comes from aria-labelledby, accessibilityLabelledBy, aria-label, and accessibilityLabel props. If none are present, the element's text content is used.

Without a name parameter (or with undefined), it only checks if the element has any accessible name.

#toHaveProp()

expect(element).toHaveProp(
  name: string,
  value?: unknown,
)

Checks if the element has a prop. Without a value (or with undefined), it only checks if the prop exists. With a value, it checks if the prop's value matches.