Skip to content

Commit ae5f9d8

Browse files
thymikeemdjastrzebski
thymikee
and
mdjastrzebski
committed
docs: add migration to v7 guide (#456)
* docs: add migration to v7 guide * adjust note about ByTitle because there's no host Button component * add fire event section * mention NativeTestInstance and container * Update website/docs/MigrationV7.md Co-authored-by: Maciej Jastrzebski <[email protected]> * Update website/docs/MigrationV7.md Co-authored-by: Maciej Jastrzebski <[email protected]> * Update website/docs/MigrationV7.md Co-authored-by: Maciej Jastrzebski <[email protected]> * Update website/docs/MigrationV7.md Co-authored-by: Maciej Jastrzebski <[email protected]> Co-authored-by: Maciej Jastrzebski <[email protected]>
1 parent 6d63a4f commit ae5f9d8

File tree

1 file changed

+118
-0
lines changed

1 file changed

+118
-0
lines changed

‎website/docs/MigrationV7.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
id: migration-v7
3+
title: Migration to 7.0
4+
---
5+
6+
:::caution
7+
We renamed the `react-native-testing-library` npm package to `@testing-library/react-native`, joining the Testing Library family.
8+
:::
9+
10+
As the version 7.0 involves merging two libraries together, there are two variants for migration guide, dependent on library you used previously:
11+
12+
- [guide for `react-native-testing-library` users](#guide-for-react-native-testing-library-users)
13+
- [guide for `@testing-library/react-native` users](#guide-for-testing-libraryreact-native-users)
14+
15+
# Guide for `react-native-testing-library` users
16+
17+
This guide describes steps necessary to migrate from React Native Testing Library `v2.x` to `v7.0`.
18+
19+
## Renaming the library
20+
21+
1. Install `@testing-library/react-native`.
22+
1. Uninstall `react-native-testing-library`.
23+
1. Rename all references of `react-native-testing-library` to `@testing-library/react-native`.
24+
25+
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](https://github.com/testing-library/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.
26+
27+
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.
28+
29+
## New aliases
30+
31+
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:
32+
33+
- `ByLabelText` aliasing `ByA11yLabel` queries
34+
- `ByHintText` aliasing `ByA11yHint` queries
35+
- `ByRole` aliasing `ByA11yRole` queries
36+
37+
We like the new names and consider removing the aliases in future releases.
38+
39+
## Renaming `ByPlaceholder` queries
40+
41+
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:
42+
43+
- `ByPlaceholder` -> `ByPlaceholderText`
44+
45+
Please replace all occurrences of these queries in your codebase.
46+
47+
# Guide for `@testing-library/react-native` users
48+
49+
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](https://github.com/callstack/react-native-testing-library). We made sure the upgrade path is as easy for you as possible.
50+
51+
## Changed helpers
52+
53+
- `getQueriesForElement` is removed, rename it to `within`
54+
- `wait` and `waitForElement` is removed, rename these to `waitFor`
55+
56+
## Missing queries
57+
58+
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 normal `Text` component under the hood.
59+
60+
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.
61+
62+
## No custom Jest configuration
63+
64+
Use the official React Native preset for Jest:
65+
66+
```diff
67+
{
68+
"jest": {
69+
- "preset": "@testing-library/react-native"
70+
+ "preset": "react-native"
71+
}
72+
}
73+
```
74+
75+
We're told this should also speed 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.
76+
77+
## Cleanup is included by default
78+
79+
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:
80+
81+
```diff
82+
{
83+
"jest": {
84+
- "setupFilesAfterEnv": ["@testing-library/react-native/cleanup-after-each"]
85+
}
86+
}
87+
```
88+
89+
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.
90+
91+
## No special handling for `disabled` prop
92+
93+
The `disabled` prop on "Touchable\*" components is treated in the same manner as any other prop. We realize that with our library you can press "touchable" components even though they're in "disabled" state, however this is something that we strongly believe should be fixed upstream, in React Native core.
94+
95+
If you feel strongly about this difference, please send a PR to React Native, adding JavaScript logic to "onPress" functions, making them aware of disabled state in JS logic as well (it's handled on native side for at least iOS, which is the default platform that tests are running in).
96+
97+
As a mitigation, you'll likely need to modify the logic of "touchable" components to bail if they're pressed in disabled state.
98+
99+
## No [NativeTestInstance](https://www.native-testing-library.com/docs/api-test-instance) abstraction
100+
101+
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.
102+
103+
## No `container` returned from `render`
104+
105+
There's no such key returned from the `render` function. If you must, use `react-test-renderer` directly, although we advise not doing so.
106+
107+
## Firing events changes
108+
109+
There are slight differences in how `fireEvent` works in both libraries:
110+
111+
1. Our library doesn't perform validation checks for events fired upon tested components.
112+
1. Signature is different:
113+
```diff
114+
-fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent)
115+
+fireEvent(element: ReactTestInstance, eventName: string, ...data: Array<any>)
116+
```
117+
1. There is no `NativeTestEvent` - second and rest arguments are used instead.
118+
1. There are only 3 short-hand events: [`fireEvent.press`](`/docs/api/#fireeventpress-element-reacttestinstance--void`), [`fireEvent.changeText`](https://callstack.github.io/react-native-testing-library/docs/api/#fireeventchangetext-element-reacttestinstance-data-arrayany--void), [`fireEvent.scroll`](https://callstack.github.io/react-native-testing-library/docs/api/#fireeventchangetext-element-reacttestinstance-data-arrayany--void). For all other or custom events you can use the base signature.

0 commit comments

Comments
 (0)