Migration to 7.0
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:
Guide for react-native-testing-library
users​
This guide describes steps necessary to migrate from React Native Testing Library v2.x
or v6.0
to v7.0
.
Renaming the library​
- Install
@testing-library/react-native
. - Uninstall
react-native-testing-library
. - Rename all references of
react-native-testing-library
to@testing-library/react-native
.
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.
New aliases​
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:
ByLabelText
aliasingByA11yLabel
queriesByHintText
aliasingByA11yHint
queriesByRole
aliasingByA11yRole
queries
We like the new names and consider removing the aliases in future releases.
Renaming ByPlaceholder
queries​
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:
ByPlaceholder
->ByPlaceholderText
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.
Guide for @testing-library/react-native
users​
This guide describes steps necessary to migrate from @testing-library/react-native
from v6.0
to 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​
The wait
and waitForElement
helpers are replaced by waitFor
. Please rename all occurrences of these in your codebase.
Changes to ByTestId
queries​
The ByTestId
queries don't accept RegExps. Please use strings instead. We're happy to accept PRs adding this functionality :).
No ByTitle
queries​
Our library doesn't implement ByTitle
queries, which are targetting components with title
prop, specifically Button
and 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. UNSAFE_getByProps({title})
query.
No custom Jest configuration​
Use the official React Native preset for Jest:
{
"jest": {
- "preset": "@testing-library/react-native"
+ "preset": "react-native"
}
}
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:
{
"jest": {
- "setupFilesAfterEnv": ["@testing-library/react-native/cleanup-after-each"]
}
}
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.
No NativeTestInstance abstraction​
We don't provide any abstraction over ReactTestInstance
returned by queries, but allow to use it directly to access queried component's props
or type
for that example.
No container
nor baseElement
returned from render
​
There's no 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 document.documentElement
nor container
.
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.press
,fireEvent.changeText
andfireEvent.scroll
. For all other or custom events you can use the base signature.