diff --git a/README.md b/README.md index df64e87b3..b682220e3 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ The [public API](https://callstack.github.io/react-native-testing-library/docs/a ## Troubleshooting -- [Understanding `act` function](https://callstack.github.io/react-native-testing-library/docs/understanding-act) +- [Troubleshooting guide](https://callstack.github.io/react-native-testing-library/docs/troubleshooting) ## Related External Resources diff --git a/website/docs/Troubleshooting.md b/website/docs/Troubleshooting.md new file mode 100644 index 000000000..6916c47d9 --- /dev/null +++ b/website/docs/Troubleshooting.md @@ -0,0 +1,41 @@ +--- +id: troubleshooting +title: Troubleshooting +--- + +This guide describes common issues found by users when integrating React Native Test Library to their projects. + +## Matching React Native, React & React Test Renderer versions + +Check that you have matching versions of core dependencies: +- React Native +- React +- React Test Renderer + +React Native uses different versioning scheme from React, you can use [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) to find the correct matching between React Native & React versions. In case you use Expo, you should use dependency versions recommended by them and set by `expo upgrade` command. + +React Test Renderer usually has same major & minor version as React, as they are closely related and React Test Renderer is part of [React monorepo](https://github.com/facebook/react). + +Related issues: +- [#1061](https://github.com/callstack/react-native-testing-library/issues/1061) +- [#938](https://github.com/callstack/react-native-testing-library/issues/938) +- [#920](https://github.com/callstack/react-native-testing-library/issues/920) + +## Example repository + +We maintain an [example repository](https://github.com/callstack/react-native-testing-library/tree/main/examples/basic) that showcases a modern React Native Testing Library setup with TypeScript, Jest Native, etc. + +In case something does not work in your setup you can refer to this repository for recommended configuration. + +## Act warnings + +When writing tests you may encounter warnings connected with `act()` function. There are two kinds of these warnings: + +* sync `act()` warning - `Warning: An update to Component inside a test was not wrapped in act(...)` +* async `act()` warning - `Warning: You called act(async () => ...) without await` + +You can read more about `act()` function in our [understanding `act` function guide](https://callstack.github.io/react-native-testing-library/docs/understanding-act). + +Normally, you should not encounter sync `act()` warnings, but if that happens this probably indicate an issue with your test and should be investigated. + +In case of async `act()` function this might happen more or less randomly, especially if your components contain async logic. So far this warning does not seem to affect test correctness. diff --git a/website/sidebars.js b/website/sidebars.js index d35d024aa..ec1738b48 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -9,6 +9,7 @@ module.exports = { 'migration-v2', 'how-should-i-query', 'faq', + 'troubleshooting', 'eslint-plugin-testing-library', 'understanding-act', ],