@testing-library/react-native 12.1.1 → 12.1.3

package/website/docs/EslintPLluginTestingLibrary.md

@@ -0,0 +1,28 @@
+---
+id: eslint-plugin-testing-library
+title: ESLint Plugin Testing Library Compatibility
+---
+
+Most of the rules of the [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library) are compatible with this library except the following:
+
+- [prefer-user-event](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/prefer-user-event.md): `userEvent` requires a DOM environment so it is not compatible with this library
+
+Also, some rules have become useless, unless maybe you're using an old version of the library:
+
+- [prefer-wait-for](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/prefer-wait-for.md): the wait utility is no longer available
+
+- [no-wait-for-empty-callback](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/no-wait-for-empty-callback.md): waitFor callback param is no longer optional
+
+To get the rule [consistent-data-testid](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/rules/consistent-data-testid.md) to work, you need to configure it to check the testID attribute by adding the following in your eslint config file, the `testIdPattern` being whichever pattern you want to enforce:
+
+```javascript
+{
+  "testing-library/consistent-data-testid": [
+    2,
+    {
+      "testIdAttribute": ["testID"],
+      "testIdPattern": "^TestId(__[A-Z]*)?$"
+    }
+  ]
+}
+```

package/website/docs/FAQ.md

@@ -0,0 +1,44 @@
+---
+id: faq
+title: FAQ
+---
+
+<details>
+  <summary>Can I test native features of React Native apps?</summary>
+
+<p>Short answer: no.</p>
+
+React Native Testing Library does not provide a full React Native runtime since that would require running on physical device
+or iOS simulator/Android emulator to provision the underlying OS and platform APIs.
+
+Instead of using React Native renderer, it simulates only the JavaScript part of its runtime by
+using [React Test Renderer](https://reactjs.org/docs/test-renderer.html) while providing queries
+and `fireEvent` APIs that mimick certain behaviors from the real runtime.
+
+You can learn more about our testing environment [here](./TestingEnvironment.md).
+
+This approach has certain benefits and shortfalls. On the positive side:
+
+- it allows testing most of the logic of regular React Native apps
+- it allows running test on any OS supported by Jest, or other test runner, e.g. on CI
+- it uses much less resources than full runtime simulation
+- you can use Jest fake timers
+
+The the negative side:
+
+- you cannot test native features
+- certain JavaScript features might not be perfectly simulated, but we are working on it
+
+For instance, [react-native's ScrollView](https://reactnative.dev/docs/scrollview) has several props that depend on native calls. While you can trigger `onScroll` call with `fireEvent.scroll`, `onMomentumScrollBegin` is called from the native side and will therefore not be called.
+
+</details>
+
+<details>
+  <summary>Should I use/migrate to `screen` queries?</summary>
+
+There is no need to migrate existing test code to use `screen`-bases queries. You can still use
+queries and other functions returned by `render`. In fact `screen` hold just that value, the latest `render` result.
+
+For newer code you can either use `screen` or `render` result destructuring. However, there are some good reasons to use `screen`, which are described in [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) by Kent C. Dodds.
+
+</details>

package/website/docs/GettingStarted.md

@@ -0,0 +1,100 @@
+---
+id: getting-started
+title: Getting Started
+---
+
+## The problem
+
+You want to write maintainable tests for your React Native components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.
+
+## This solution
+
+The React Native Testing Library (RNTL) is a lightweight solution for testing React Native components. It provides light utility functions on top of `react-test-renderer`, in a way that encourages better testing practices. Its primary guiding principle is:
+
+> The more your tests resemble the way your software is used, the more confidence they can give you.
+
+This project is inspired by [React Testing Library](https://github.com/testing-library/react-testing-library). Tested to work with Jest, but it should work with other test runners as well.
+
+You can find the source of `QuestionsBoard` component and this example [here](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/questionsBoard.test.tsx).
+
+## Installation
+
+Open a Terminal in your project's folder and run:
+
+#### Using `yarn`
+
+```sh
+yarn add --dev @testing-library/react-native
+```
+
+#### Using `npm`
+
+```sh
+npm install --save-dev @testing-library/react-native
+```
+
+This library has a `peerDependencies` listing for `react-test-renderer`. Make sure that your `react-test-renderer` version matches exactly your `react` version.
+
+:::info
+In order to properly use helpers for async tests (`findBy` queries and `waitFor`) you need at least React >=16.9.0 (featuring async `act`) or React Native >=0.61 (which comes with React >=16.9.0).
+:::
+
+### Additional Jest matchers
+
+In order to use addtional React Native-specific jest matchers from [@testing-library/jest-native](https://github.com/testing-library/jest-native) package add it to your project:
+
+#### Using `yarn`
+
+```sh
+yarn add --dev @testing-library/jest-native
+```
+
+#### Using `npm`
+
+```sh
+npm install --save-dev @testing-library/jest-native
+```
+
+Then automatically add it to your jest tests by using `setupFilesAfterEnv` option in your Jest configuration (it's usually located either in `package.json` under `"jest"` key or in a `jest.config.js` file):
+
+```json
+{
+  "preset": "react-native",
+  "setupFilesAfterEnv": ["@testing-library/jest-native/extend-expect"]
+}
+```
+
+### Flow
+
+Note for [Flow](https://flow.org) users – you'll also need to install typings for `react-test-renderer`:
+
+```sh
+flow-typed install react-test-renderer
+```
+
+## Example
+
+```jsx
+import { render, screen, fireEvent } from '@testing-library/react-native';
+import { QuestionsBoard } from '../QuestionsBoard';
+
+test('form submits two answers', () => {
+  const allQuestions = ['q1', 'q2'];
+  const mockFn = jest.fn();
+
+  render(<QuestionsBoard questions={allQuestions} onSubmit={mockFn} />);
+
+  const answerInputs = screen.getAllByLabelText('answer input');
+
+  fireEvent.changeText(answerInputs[0], 'a1');
+  fireEvent.changeText(answerInputs[1], 'a2');
+  fireEvent.press(screen.getByText('Submit'));
+
+  expect(mockFn).toBeCalledWith({
+    1: { q: 'q1', a: 'a1' },
+    2: { q: 'q2', a: 'a2' },
+  });
+});
+```
+
+You can find the source of `QuestionsBoard` component and this example [here](https://github.com/callstack/react-native-testing-library/blob/main/src/__tests__/questionsBoard.test.tsx).

package/website/docs/HowShouldIQuery.md

@@ -0,0 +1,21 @@
+---
+id: how-should-i-query
+title: How Should I Query?
+---
+
+## Priority
+
+Based on the [Guiding Principles](https://testing-library.com/docs/guiding-principles), your test should resemble how users interact with your code (component, page, etc.) as much as possible. With this in mind, we recommend this order of priority:
+
+1. **Queries Accessible to Everyone** queries that reflect the experience of visual users as well as those that use assistive technology
+   - [`getByText`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bytext): This is the number 1 method a user finds any visible text on interactive and non-interactive elements.
+   - [`getByDisplayValue`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bydisplayvalue): Useful for the current value of a `TextInput`.
+   - [`getByPlaceholderText`](https://callstack.github.io/react-native-testing-library/docs/api-queries#byplaceholdertext): Only useful for targeting a placeholder of a `TextInput`.
+   - [`getByLabelText`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bylabeltext): This can be used to query every element that is exposed in the accessibility tree as a label, usually when there's no visible text.
+   - [`getByHintText`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bya11yhint-byaccessibilityhint-byhinttext): This can be used to query every element that is exposed in the accessibility tree as a hint. Make sure it also has a label set.
+   - [`getByAccessibilityState`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bya11ystate-byaccessibilitystate): This can be used to query every element that is exposed in the accessibility tree as a state of an interactive element, like a checkbox.
+   - [`getByAccessibilityValue`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bya11value-byaccessibilityvalue): This can be used to query every element that is exposed in the accessibility tree as a value on a range, like a slider.
+2. **Queries Users Can Infer**
+   - [`getByRole`](https://callstack.github.io/react-native-testing-library/docs/api-queries#byrole): This can be used to query every element that is exposed in the accessibility tree as a role, like buttons or images.
+3. **Test IDs**
+   - [`getByTestId`](https://callstack.github.io/react-native-testing-library/docs/api-queries#bytestid): The user cannot see (or hear) these, so this is only recommended for cases where you can't match by text or it doesn't make sense

package/website/docs/MigrationV11.md

@@ -0,0 +1,64 @@
+---
+id: migration-v11
+title: Migration to 11.0
+---
+
+Migration to React Native Testing Library version 11 from version 9.x or 10.x should be a relatively easy task due small amount of breaking changes.
+
+# Breaking changes
+
+## Update to Jest 28 if you use fake timers
+
+If you use fake timers in any of your tests you should update your Jest dependencies to version 28. This is due to the fact that [`jest.useFakeTimers()` config structure](https://jestjs.io/docs/jest-object#jestusefaketimersfaketimersconfig) has changed.
+
+## Refactor legacy `waitForOptions` position
+
+In version 9 we introducted query `options` parameters for each query type. This affected all `findBy` and `findAllBy` queries because their signatures changed e.g. from:
+
+```ts
+function findByText(text: TextMatch, waitForOptions?: WaitForOptions)
+function findAllByText(text: TextMatch, waitForOptions?: WaitForOptions)
+```
+
+to 
+
+```ts
+function findByText(text: TextMatch, options?: TextMatchOptions, waitForOptions?: WaitForOptions)
+function findAllByText(text: TextMatch, options?: TextMatchOptions, waitForOptions?: WaitForOptions)
+```
+
+In order to facilitate transition, in version 9 and 10, we provided a temporary possibility to pass `WaitForOptions` like `timeout`, `interval`, etc inside `options` argument. From this release we require passing these as the proper third parameter.
+
+This change is easy to implement:
+
+```ts
+findByText(/Text/, { timeout: 1000 })
+```
+
+should become
+
+```ts
+findByText(/Text/, {}, { timeout: 1000 })
+```
+
+## Triggering non-touch events on targets with `pointerEvents="box-none"` prop
+
+Up to version 10, RNTL disables all events for a target with `pointerEvents="box-none"`. This behavior is counter to how React Native itself functions. 
+
+From version 11, RNTL continues to disable `press` event for these targets but allows triggering other events, e.g. `layout`.
+
+# All changes
+
+* chore(breaking): update Jest to 28 by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1008
+* refactor(breaking): remove legacy wait for options support by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1018
+* refactor(breaking): remove `byA11yStates` queries by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1015
+* chore: update react-native to 0.69.1 by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1010
+* chore: update deps @types for react/react-native by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1013
+* feat: Trigger non-touch events on box-none targets by @dcalhoun in https://github.com/callstack/react-native-testing-library/pull/906
+* docs: create document describing act function and related errors by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/969
+* chore: Organise a11y queries by predicate by @MattAgn in https://github.com/callstack/react-native-testing-library/pull/977
+* chore: reenable skipped byText tests by @mdjastrzebski in https://github.com/callstack/react-native-testing-library/pull/1017
+
+# Full Changelog
+https://github.com/callstack/react-native-testing-library/compare/v10.1.1...v11.0.0
+

package/website/docs/MigrationV12.md

@@ -0,0 +1,67 @@
+---
+id: migration-v12
+title: Migration to 12.0
+---
+
+React Native Testing Library 12 introduces a handful of breaking changes compared to 11.x versions. We believe they were necessary to improve the experience using the library and help the users [fall into the pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/) when writing meaningful tests. You will find migration instructions for each and every change described below.
+
+:::note
+If you use [Jest Native matchers](https://github.com/testing-library/jest-native), which we recommend, then you should upgrade it to version 5.4.2 or higher.
+:::
+
+# Breaking changes
+
+## 1. All queries exclude elements hidden from accessibility by default
+Elements that are hidden from accessiblity, e.g. elements on non-active screen when using React Navigation, now will not be matched by default by all queries. This is the effect of switching the default value for global config option `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) to `false`.
+
+Previous behaviour of matching hidden elements can be enabled on query level using [includeHiddenElements](api-queries#includehiddenelements-option) query options or globally using `defaultIncludeHiddenElements`(api#defaultincludehiddenelements-option) configuration option.
+
+## 2. `*ByRole` queries now return only accessibility elements
+`*ByRole` queries now return only accessibility elements, either explicitly marked with `accessible` prop or implicit ones where this status is derived from component type itself (e.g `Text`, `TextInput`, `Switch`, but not `View`).
+
+You may need to adjust relevant components under test to make sure they pass `isAccessibilityElement` check.
+
+### Examples
+Let's assume we are using `getByRole("button")` query.
+
+Following elements will match:
+
+```ts
+// Explicit "accessible" prop for View
+<View accessible accessibilityRole="button" />
+
+// No need to "accessible" prop for Text, as it is implicitly accessible element.
+<Text accessibilityRole="button">Button</Text>
+```
+
+While following elements will not match:
+
+```ts
+// Missing "accessible" prop for View
+<View accessibilityRole="button" />
+
+// Explicit "accessible={false}" prop for View
+<View accessible={false} accessibilityRole="button" />
+
+// Explicit "accessible={false}" for Text, which is implicitly accessible element
+<Text accessible={false} accessibilityRole="button">Button</Text>
+```
+
+## 3. `*ByText`, `*ByDisplayValue`, `*ByPlaceholderText` queries now return host elements
+`*ByText`, `*ByDisplayValue`, `*ByPlaceholderText` queries now return [host elements](testing-env#host-and-composite-components), which is consistent with other queries.
+
+While potentially breaking, this should not cause issues in tests if you are using recommended queries and Jest Matchers from Jest Native package. 
+
+Problematic cases may include: directly checking some prop values (without using Jest Native matchers), referencing other nodes using `parent` or `children` props, examining `type` property of `ReactTestInstance`, etc.
+
+## 4. `container` API has been renamed to `UNSAFE_root`.
+
+Historically `container` was supposed to mimic the [RTL's container](https://testing-library.com/docs/react-testing-library/api/#container). However it turned out not so relevant in RNTL's environment, where we actually used it to return React Test Renderer's root instance.
+
+RNTL v12 introduces `root` API as an alternative that returns a root **host** element. The difference between `root` and `UNSAFE_root` properties is that that `root` will always represents a host element, while `UNSAFE_root` will typically represent a composite element.
+
+If you use `toBeOnTheScreen` matcher from [@testing-library/jest-native](https://github.com/testing-library/jest-native) your tests will fail because it uses the `container` api. To fix this, update `@testing-library/jest-native` to version 5.4.2.    
+
+# Full Changelog
+https://github.com/callstack/react-native-testing-library/compare/v11.5.2...v11.5.2...v12.0.0-rc.0
+

package/website/docs/MigrationV2.md

@@ -0,0 +1,126 @@
+---
+id: migration-v2
+title: Migration to 2.0
+---
+
+This guide describes steps necessary to migrate from React Native Testing Library `v1.x` to `v2.0`.
+
+## Dropping Node 8
+
+Node 8 reached its EOL more than 5 months ago, so it's about time to target the library to Node 10. If you used lower version, you'll have to upgrade to v10, but we recommend using the latest LTS version.
+
+## Auto Cleanup
+
+`cleanup()` function is now called automatically after every test if your testing framework supports `afterEach` hook (like Jest, Mocha, and Jasmine).
+
+You should be able to remove all `afterEach(cleanup)` calls in your code.
+
+This change might break your code, if you tests are not isolated, i.e. you call `render` outside `test` block. Generally, you should [keep your tests isolated](https://kentcdodds.com/blog/test-isolation-with-react). But if you can't or don't want to do this right away you can prevent this behavior using any of the following ways:
+
+- by importing `'react-native-testing-library/pure'` instead of `'react-native-testing-library'`
+- by importing `'react-native-testing-library/dont-cleanup-after-each'` before importing `'react-native-testing-library'`. You can do it in a global way by using Jest's `setupFiles` like this:
+
+  ```json
+  {
+    "setupFiles": ["react-native-testing-library/dont-cleanup-after-each"];
+  }
+  ```
+
+- by setting `RNTL_SKIP_AUTO_CLEANUP` env variable to `true`. You can do this with `cross-evn` like this:
+
+  ```sh
+  cross-env RNTL_SKIP_AUTO_CLEANUP=true jest
+  ```
+
+## WaitFor API changes
+
+We renamed `waitForElement` function to `waitFor` for consistency with React Testing Library. Additionally, the signature has slightly changed from:
+
+```jsx
+export default function waitForElement<T>(
+  expectation: () => T,
+  timeout?: number,
+  interval?: number
+): Promise<T> {}
+```
+
+to:
+
+```jsx
+export default function waitFor<T>(
+  expectation: () => T,
+  options: {
+    timeout?: number,
+    interval?: number,
+  }
+): Promise<T> {}
+```
+
+Both changes should improve code readibility.
+
+`waitFor` calls (and hence also `findBy` queries) are now wrapped in `act` by default, so that you should no longer need to use `act` directly in your tests.
+
+:::tip
+You can usually avoid `waitFor` by a proper use of `findBy` asynchronous queries. It will result in more streamlined testing experience.
+:::
+
+## Removed global `debug` function
+
+The `debug()` method returned from `render()` function is all you need. We removed the global export to avoid confusion.
+
+## Removed global `shallow` function
+
+Shallow rendering React component is usually not a good idea, so we decided to remove the API. But, if you find it useful or need to support legacy tests, feel free to use this implementation:
+
+```js
+import ShallowRenderer from 'react-test-renderer/shallow';
+
+export function shallow(instance: ReactTestInstance | React.Element<any>) {
+  const renderer = new ShallowRenderer();
+  renderer.render(React.createElement(instance.type, instance.props));
+
+  return { output: renderer.getRenderOutput() };
+}
+```
+
+## Removed functions
+
+Following query functions have been removed after being deprecated for more than a year now:
+
+- `getByName`
+- `getAllByName`
+- `queryByName`
+- `queryAllByName`
+
+The `*ByType` and `*ByProps` queries has been prefixed with `UNSAFE_`. These `UNSAFE_` functions are not planned for removal in future versions but their usage is discouraged. You can rename them using global search/replace in your project:
+
+- `getByType` -> `UNSAFE_getByType`
+- `getAllByType` -> `UNSAFE_getAllByType`
+- `queryByType` -> `UNSAFE_queryByType`
+- `queryAllByType` -> `UNSAFE_queryAllByType`
+- `getByProps` -> `UNSAFE_getByProps`
+- `getAllByProps` -> `UNSAFE_getAllByProps`
+- `queryByProps` -> `UNSAFE_queryByProps`
+- `queryAllByProps` -> `UNSAFE_queryAllByProps`
+
+## Some `ByTestId` queries behavior changes
+
+In version `1.x` the `getByTestId` and `queryByTestId` queries could return non-native instances. This was a serious bug. Other query functions like `getAllByTestId`, `queryAllByTestId`, `findByTestId` and `findAllByTestId` didn't have this issue. These correctly returned only native components instances (e.g. `View`, `Text`, etc) that got the `testID`.
+
+In v2 we fixed this inconsistency, which may result in failing tests, if you relied on this behavior. There are few ways to handle these failures:
+
+- pass the `testID` prop down so it can reach a native component, like `View` or `Text`
+- replace `testID` with proper `accessibilityHint` or `accessibilityLabel` if it benefits the user
+- use safe queries like `*ByText` or `*ByA11yHint`
+
+## Deprecated `flushMicrotasksQueue`
+
+We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major. We have better alternatives available for helping you write async tests – `findBy` async queries and `waitFor` helper.
+
+If you can't or don't want to migrate your tests, don't worry. You can use the same implementation we have today:
+
+```js
+function flushMicrotasksQueue() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+```

package/website/docs/MigrationV7.md

@@ -0,0 +1,119 @@
+---
+id: migration-v7
+title: Migration to 7.0
+---
+
+:::caution
+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](#guide-for-react-native-testing-library-users)
+- [Guide for `@testing-library/react-native` users](#guide-for-testing-libraryreact-native-users)
+
+# 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
+
+1. Install `@testing-library/react-native`.
+1. Uninstall `react-native-testing-library`.
+1. 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](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.
+
+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` aliasing `ByA11yLabel` queries
+- `ByHintText` aliasing `ByA11yHint` queries
+- `ByRole` aliasing `ByA11yRole` 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](https://github.com/callstack/react-native-testing-library). 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:
+
+```diff
+{
+  "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:
+
+```diff
+{
+  "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](https://www.native-testing-library.com/docs/api-test-instance) 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:
+
+1. Our library doesn't perform validation checks for events fired upon tested components.
+1. Signature is different:
+   ```diff
+   -fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent)
+   +fireEvent(element: ReactTestInstance, eventName: string, ...data: Array<any>)
+   ```
+1. There is no `NativeTestEvent` - second and rest arguments are used instead.
+1. There are only 3 short-hand events: [`fireEvent.press`](api/#fireeventpress-element-reacttestinstance--void), [`fireEvent.changeText`](api/#fireeventchangetext-element-reacttestinstance-data-arrayany--void) and [`fireEvent.scroll`](api/#fireeventscroll-element-reacttestinstance-data-arrayany--void). For all other or custom events you can use the base signature.

package/website/docs/MigrationV9.md

@@ -0,0 +1,67 @@
+---
+id: migration-v9
+title: Migration to 9.0
+---
+
+Version 7.0 brought React Native Testing Library into the `@testing-library` family. Since it has been implemented independently from its web counterpart – the React Testing Library – there are some differences in the API and behavior. Version 9.0 solves several of these problems.
+
+## Support for text match options a.k.a string precision API
+
+This is a backward compatible change.
+
+When querying text, it is now possible to pass a [`TextMatch`](https://callstack.github.io/react-native-testing-library/docs/api-queries/#textmatch) to most text based queries, which lets you configure how `@testing-library/react-native` should match your text. For instance, passing `exact: false` will allow matching substrings and will ignore case:
+
+```jsx
+const { getByText } = render(<Text>Hello World</Text>);
+
+getByText('Hello World'); // Matches
+getByText('Hello'); // Doesn't match
+getByText('hello', { exact: false }); // ignore case-sensitivity and does partial matching
+```
+
+Please note that the `findBy*` queries used to take a `waitForOptions` parameter as a second argument, which has now been moved to the third argument:
+
+```diff
+-findByText('Hello world', { timeout: 3000 }); // old findBy* API
++findByText('Hello world', {}, { timeout: 3000 }); // new findBy* API
+```
+
+For backward compatibility RNTL v9 can still read `waitForOptions` from the second argument but will print a deprecation warning.
+
+## Reverted matching text across several nodes
+
+:::caution
+This is a breaking change.
+:::
+
+In v1.14 we've introduced a feature allowing to match text when it's spread across several nodes:
+
+```tsx
+const { getByText } = render(
+  <Text>
+    Hello <Text>world</Text>
+  </Text>
+);
+getByText('Hello world'); // matches
+```
+
+However this behavior was different than the web one, and wouldn't always be straightforward to reason about. For instance it could match text nodes far from each other on the screen. It also prevented us from implementing the string precision API. From v9, this type of match will not work.
+
+A work around is to use `within`:
+
+```tsx
+import {Text} from 'react-native'
+import {render, within} from '@testing-library/react-native'
+
+const {getByText} = render(<Text>Hello <Text>world</Text</Text>)
+
+within(getByText('Hello', {exact: false})).getByText('world')
+```
+
+## Future plans
+
+This release changes a lot of internal logic in the library, paving the way for more improvements to bring us closer to our web counterpart, with a possibly better story for accessibility queries.
+
+We're also [migrating the codebase to TypeScript](https://github.com/callstack/react-native-testing-library/issues/877). Please let us know if you're interested in helping us with this effort.
+
+Stay safe!