We renamed the
react-native-testing-library npm package to
@testing-library/react-native, officially joining the "Testing Library" family 🎉.
As the version 7.0 involves merging two libraries together, there are two variants for migration guide, dependent on library you used previously:
This guide describes steps necessary to migrate from React Native Testing Library
Renaming the library
- Rename all references of
You may have noticed a strange v2 to v7 upgrade, skipping versions 3, 4, 5 and 6. This is because we renamed the
react-native-testing-library npm package to
@testing-library/react-native, officially joining the "Testing Library" family 🎉. We're merging existing two libraries into a single one. The native-testing-library repository, which had v6, will soon be archived and using
@testing-library/react-native below v7, sourced from mentioned repository, is deprecated.
For branding purposes we keep the "React Native Testing Library" name, similar to "React Testing Library". Only the npm published package is changing. The code repository also stays the same under Callstack governance.
To improve compatibility with React Testing Library, and ease the migration for
@testing-library/react-native users using version below v7, we've introduced new aliases to our accessibility queries:
We like the new names and consider removing the aliases in future releases.
To improve compatibility with React Testing Library, and to ease the migration for
@testing-library/react-native users using version below v7, we've renamed following queries:
Please replace all occurrences of these queries in your codebase.
fireEvent support for disabled components
To improve compatibility with the real React Native environment
fireEvent now performs checks whether the component is "disabled" before firing an event on it. It uses the Responder system to establish should the event fire, which resembles the actual React Native runtime closer than we used to.
If your code contained any workarounds for preventing events firing on disabled events, you should now be able to remove them.
This guide describes steps necessary to migrate from
v7.0. Although the name stays the same, this is a different library, sourced at Callstack GitHub repository. We made sure the upgrade path is as easy for you as possible.
Renaming "wait" helpers
waitForElement helpers are replaced by
waitFor. Please rename all occurrences of these in your codebase.
ByTestId queries don't accept RegExps. Please use strings instead. We're happy to accept PRs adding this functionality :).
Our library doesn't implement
ByTitle queries, which are targetting components with
title prop, specifically
RefreshControl. If your tests only use
ByTitle to target
Button components, you can replace them with
ByText queries, since React Native renders
Text under the hood.
If you need to query
RefreshControl component and can't figure out other way around it, you can use e.g.
No custom Jest configuration
Use the official React Native preset for Jest:
We're told this also speeds up your tests startup on cold cache. Using official preset has another benefit – the library is compatible with any version of React Native without introducing breaking changes.
Cleanup is included by default
Cleaning up (unmounting) components after each test is included by default in the same manner as in React Testing Library. Please remove this setup file from Jest config:
You can opt-out of this behavior by running tests with
RNTL_SKIP_AUTO_CLEANUP=true flag or importing from
@testing-library/react-native/pure. We encourage you to keep the default though.
We don't provide any abstraction over
ReactTestInstance returned by queries, but allow to use it directly to access queried component's
type for that example.
baseElement returned from
container returned from the
render function. If you must, use
react-test-renderer directly, although we advise against doing so. We also don't implement
baseElement because of that, since there's no
Firing events changes
There are slight differences in how
fireEvent works in both libraries:
- Our library doesn't perform validation checks for events fired upon tested components.
- Signature is different:-fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent)+fireEvent(element: ReactTestInstance, eventName: string, ...data: Array<any>)
- There is no
NativeTestEvent- second and rest arguments are used instead.
- There are only 3 short-hand events:
fireEvent.scroll. For all other or custom events you can use the base signature.