jest-matchers.md

Jest matchers

This guide covers the built-in Jest matchers. These matchers make your tests easier to read and work better with accessibility features.

Setup

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

Checking element existence

toBeOnTheScreen()

expect(element).toBeOnTheScreen();

Checks if an element is attached to the element tree. If you have a reference to an element and it gets unmounted during the test, this assertion will fail.

Element Content

toHaveTextContent()

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

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

toContainElement()

expect(container).toContainElement(
  instance: TestInstance | null,
)

Checks if a container element contains another element.

toBeEmptyElement()

expect(element).toBeEmptyElement();

Checks if an 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 like exact and normalizer.

toHaveAccessibilityValue()

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

Checks if an element has the specified accessible value.

The matcher reads accessibility values from aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, and accessibilityValue props. It only checks the values you specify, so the element can have other accessibility value entries and still match.

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

toBeEnabled() / toBeDisabled

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

Checks if an element is enabled or disabled from aria-disabled or accessibilityState.disabled props. An element is disabled if it or any ancestor is disabled.

Note

These matchers are opposites. Both are available so you can avoid double negations like expect(element).not.toBeDisabled().

toBeSelected()

expect(element).toBeSelected();

Checks if an element is selected from aria-selected or accessibilityState.selected props.

toBeChecked() / toBePartiallyChecked()

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

Checks if an element is checked or partially checked from aria-checked or accessibilityState.checked props.

Note

• toBeChecked() only works on Switch host elements and elements with checkbox, radio, or switch role.
• toBePartiallyChecked() only works on elements with checkbox role.

toBeExpanded() / toBeCollapsed()

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

Checks if an element is expanded or collapsed from aria-expanded or accessibilityState.expanded props.

Note

These matchers are opposites for expandable elements (those with explicit aria-expanded or accessibilityState.expanded props). For non-expandable elements, neither matcher will pass.

toBeBusy()

expect(element).toBeBusy();

Checks if an element is busy from aria-busy or accessibilityState.busy props.

Checking element style

toBeVisible()

expect(element).toBeVisible();

Checks if an element is visible.

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

toHaveStyle()

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

Checks if an element has specific styles.

Other matchers

toHaveAccessibleName()

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

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

See Accessible name for how the accessible name is derived from an element's label props and text content.

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

toHaveProp()

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

Checks if an 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.

Note

Use this matcher as a last resort when other matchers don't fit your needs.