Migration to built-in Jest matchers#

This guide describes the steps necessary to migrate from legacy Jest Native matchers v5 to built-in Jest matchers.

General notes#

All of the built-in Jest matchers provided by the React Native Testing Library support only host elements. This should not be an issue, as all RNTL v12 queries already return only host elements. When this guide states that a given matcher should work the same it assumes behavior only host elements. If you need to assert the status of composite elements use Jest Native matchers in legacy mode.

Usage#

You don't need to do anything to use the built-in matchers. They are automatically available when you import anything from @testing-library/react-native.

Gradual migration#

You can use the built-in matchers alongside legacy Jest Native matchers by changing their import in your jest-setup.ts file:

// Replace this:
// import '@testing-library/jest-native/extend-expect';

// With this:
import '@testing-library/jest-native/legacy-extend-expect';

In this case legacy matchers will be available using the legacy_ prefix, e.g.:

expect(element).legacy_toHaveAccessibilityState({ busy: true });

Migration details#

Matchers not requiring changes#

The following matchers should work the same:

• toBeEmptyElement()
• toBeEnabled() / toBeDisabled()
• toBeOnTheScreen()
• toBeVisible()
• toContainElement()
• toHaveAccessibilityValue()
• toHaveDisplayValue()
• toHaveProp()
• toHaveStyle()
• toHaveTextContent()

Replaced matchers#

The toHaveAccessibilityState() matcher has been replaced by the following matchers:

• enabled state: toBeEnabled() / toBeDisabled()
• checked state: toBeChecked() / toBePartiallyChecked()
• selected state: toBeSelected()
• expanded state: toBeExpanded() / toBeCollapsed()
• busy state: toBeBusy()

The new matchers support both accessibilityState and aria-* props.

Added matchers#

New toHaveAccessibleName() has been added.

Noteworthy details#

You should be aware of the following details:

• toBeEnabled() / toBeDisabled() matchers also check the disabled state for the element's ancestors and not only the element itself. This is the same as in legacy Jest Native matchers of the same name but differs from the removed toHaveAccessibilityState() matcher.
• toBeChecked() matcher supports only elements with a checkbox, radio and 'switch' role
• toBePartiallyChecked() matcher supports only elements with checkbox role