From d640886cddc68906854baa5be20de4c8ac1a7f03 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 20 Sep 2023 23:02:03 +0200
Subject: [PATCH 01/18] docs: v1 of jest matchers docs

---
 website/docs/JestMatchers.md | 157 +++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 website/docs/JestMatchers.md

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
new file mode 100644
index 000000000..0b74e148d
--- /dev/null
+++ b/website/docs/JestMatchers.md
@@ -0,0 +1,157 @@
+---
+id: jest-matchers
+title: Jest Matchers
+---
+
+# Element Existence
+
+## `toBeOnTheScreen()`
+
+```ts
+expect(element).toBeOnTheScreen()
+```
+
+This allows you to assert whether element is in the element tree or not.
+
+:::note
+This matchers requires element to be attached to the element tree. This might be useful if your holding a reference to an element and the element gets unmounted during the test.
+:::
+
+# Element State
+
+## `toHaveTextContent()`
+
+```ts
+expect(element).toHaveTextContent(text: TextMatch, options?: TextMatchOptions)
+```
+
+This allows you to assert whether the given element has a text content or not. It accepts either `string` or `RegExp` matchers, as well as `TextMatchOptions`.
+
+When `text` parameter is `undefined` it will only check for existence of text content, and when `text` is defined it will check if the actual text content matches passed value.
+
+## `toHaveDisplayValue()`
+
+```ts
+expect(element).toHaveDisplayValue(value: TextMatch, options?: TextMatchOptions)
+```
+
+This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as `TextMatchOptions`.
+
+## `toHaveAccessibleValue()`
+
+```ts
+expect(element).toHaveAccessibleValue(...)
+```
+
+This allows you to assert whether the given element has specified accessible value.
+
+## `toBeEnabled()` / `toBeDisabled`
+
+```ts
+expect(element).toBeEnabled()
+expect(element).toBeDisabled()
+```
+
+These allows you to assert whether the given element is enabled or disabled from user's perspective. It relies on accessibility disabled state as set by `aria-disabled` or `accessibilityState.disabled` props. It will considers given element disabled when it or any of its ancestors is disabled.
+
+:::note
+This matchers are direct negation of each other, and both are probivided to avoid double negations in your assertions.
+:::
+
+
+## `toBeSelected()`
+
+```ts
+expect(element).toBeSelected()
+```
+
+This allows you to assert whether the given element is selected from user's perspective. It relies on accessibility selected state as set by `aria-selected` or `accessibilityState.selected` props.
+
+
+## `toBeChecked()` / `toBePartiallyChecked()`
+
+```ts
+expect(element).toBeChecked()
+expect(element).toBePartiallyChecked()
+```
+
+These allows you to assert whether the given element is checked or partially checked from user's perspective. It relies on accessibility checked state as set by `aria-checked` or `accessibilityState.checked` props.
+
+:::note
+* `toBeChecked()` matcher works only on elements with `checkbox` or `radio` role.
+* `toBePartiallyChecked()` matchers works only on elements with `checkbox` role.
+:::
+
+## `toBeExpanded()` /  `toBeCollapsed()`
+
+```ts
+expect(element).toBeExpanded()
+expect(element).toBeCollapsed()
+```
+
+These allows you to assert whether the given element is expanded or collapsed from user's perspective. It relies on accessibility disabled state as set by `aria-expanded` or `accessibilityState.expanded` props.
+
+:::note
+This matchers are direct negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both with fail for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
+:::
+
+
+## `toBeBusy()`
+
+```ts
+expect(element).toBeBusy()
+```
+
+This allows you to assert whether the given element is busy from user's perspective. It relies on accessibility selected state as set by `aria-busy` or `accessibilityState.busy` props.
+
+# Element Styles
+
+## `toBeVisible()`
+
+```ts
+expect(element).toBeVisible()
+```
+
+This allows you to assert whether the given element is visible from user's perspective. 
+
+The element is considered invisibile when it or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessbility.
+
+## `toHaveStyle()`
+
+```ts
+expect(element).toHaveStyle(style: StyleProp<Style>)
+```
+
+This allows you to assert whether the given element has given styles. 
+
+
+# Other
+
+## `toBeEmptyElement()`
+
+```ts
+expect(element).toBeEmptyElement()
+```
+
+This allows you to assert whether the given element does not have any host child elements nor text content.
+
+
+## `toContainElement()`
+
+```ts
+expect(container).toContainElement(element: ReactTestInstance | null)
+```
+
+This allows you to assert whether the given container element does contain another host element.
+
+## `toHaveProp()`
+
+```ts
+expect(element).toHaveProp(name: string, value?: unknown)
+```
+
+This allows you to assert whether the given element has a given prop. When `value` parameter is `undefined` it will only check for existence of prop, and when `value` is defined it will check if the actual value matches passed value.
+
+:::note
+This matchers should be treated as escape hatch to be used when all other matchers are not suitable.
+:::
\ No newline at end of file

From 5cf655fbbb42a6869690df44abd49eb11700f130 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 20 Sep 2023 23:05:06 +0200
Subject: [PATCH 02/18] chore: add TOC

---
 website/docs/JestMatchers.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 0b74e148d..9b97db7ea 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -3,6 +3,10 @@ id: jest-matchers
 title: Jest Matchers
 ---
 
+import TOCInline from '@theme/TOCInline';
+
+<TOCInline toc={toc} />
+
 # Element Existence
 
 ## `toBeOnTheScreen()`

From 4a6d67d5c72f0b8b19adf108abe38bdf7e8ae805 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 20 Sep 2023 23:06:16 +0200
Subject: [PATCH 03/18] chore: tweak heading levels

---
 website/docs/JestMatchers.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 9b97db7ea..037458fa0 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -7,9 +7,9 @@ import TOCInline from '@theme/TOCInline';
 
 <TOCInline toc={toc} />
 
-# Element Existence
+## Element Existence
 
-## `toBeOnTheScreen()`
+### `toBeOnTheScreen()`
 
 ```ts
 expect(element).toBeOnTheScreen()
@@ -21,9 +21,9 @@ This allows you to assert whether element is in the element tree or not.
 This matchers requires element to be attached to the element tree. This might be useful if your holding a reference to an element and the element gets unmounted during the test.
 :::
 
-# Element State
+## Element State
 
-## `toHaveTextContent()`
+### `toHaveTextContent()`
 
 ```ts
 expect(element).toHaveTextContent(text: TextMatch, options?: TextMatchOptions)
@@ -33,7 +33,7 @@ This allows you to assert whether the given element has a text content or not. I
 
 When `text` parameter is `undefined` it will only check for existence of text content, and when `text` is defined it will check if the actual text content matches passed value.
 
-## `toHaveDisplayValue()`
+### `toHaveDisplayValue()`
 
 ```ts
 expect(element).toHaveDisplayValue(value: TextMatch, options?: TextMatchOptions)
@@ -41,7 +41,7 @@ expect(element).toHaveDisplayValue(value: TextMatch, options?: TextMatchOptions)
 
 This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as `TextMatchOptions`.
 
-## `toHaveAccessibleValue()`
+### `toHaveAccessibleValue()`
 
 ```ts
 expect(element).toHaveAccessibleValue(...)
@@ -49,7 +49,7 @@ expect(element).toHaveAccessibleValue(...)
 
 This allows you to assert whether the given element has specified accessible value.
 
-## `toBeEnabled()` / `toBeDisabled`
+### `toBeEnabled()` / `toBeDisabled`
 
 ```ts
 expect(element).toBeEnabled()
@@ -63,7 +63,7 @@ This matchers are direct negation of each other, and both are probivided to avoi
 :::
 
 
-## `toBeSelected()`
+### `toBeSelected()`
 
 ```ts
 expect(element).toBeSelected()
@@ -72,7 +72,7 @@ expect(element).toBeSelected()
 This allows you to assert whether the given element is selected from user's perspective. It relies on accessibility selected state as set by `aria-selected` or `accessibilityState.selected` props.
 
 
-## `toBeChecked()` / `toBePartiallyChecked()`
+### `toBeChecked()` / `toBePartiallyChecked()`
 
 ```ts
 expect(element).toBeChecked()
@@ -86,7 +86,7 @@ These allows you to assert whether the given element is checked or partially che
 * `toBePartiallyChecked()` matchers works only on elements with `checkbox` role.
 :::
 
-## `toBeExpanded()` /  `toBeCollapsed()`
+### `toBeExpanded()` /  `toBeCollapsed()`
 
 ```ts
 expect(element).toBeExpanded()
@@ -100,7 +100,7 @@ This matchers are direct negation of each other for expandable elements (element
 :::
 
 
-## `toBeBusy()`
+### `toBeBusy()`
 
 ```ts
 expect(element).toBeBusy()
@@ -108,9 +108,9 @@ expect(element).toBeBusy()
 
 This allows you to assert whether the given element is busy from user's perspective. It relies on accessibility selected state as set by `aria-busy` or `accessibilityState.busy` props.
 
-# Element Styles
+## Element Styles
 
-## `toBeVisible()`
+### `toBeVisible()`
 
 ```ts
 expect(element).toBeVisible()
@@ -120,7 +120,7 @@ This allows you to assert whether the given element is visible from user's persp
 
 The element is considered invisibile when it or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessbility.
 
-## `toHaveStyle()`
+### `toHaveStyle()`
 
 ```ts
 expect(element).toHaveStyle(style: StyleProp<Style>)
@@ -129,9 +129,9 @@ expect(element).toHaveStyle(style: StyleProp<Style>)
 This allows you to assert whether the given element has given styles. 
 
 
-# Other
+## Other
 
-## `toBeEmptyElement()`
+### `toBeEmptyElement()`
 
 ```ts
 expect(element).toBeEmptyElement()
@@ -140,7 +140,7 @@ expect(element).toBeEmptyElement()
 This allows you to assert whether the given element does not have any host child elements nor text content.
 
 
-## `toContainElement()`
+### `toContainElement()`
 
 ```ts
 expect(container).toContainElement(element: ReactTestInstance | null)
@@ -148,7 +148,7 @@ expect(container).toContainElement(element: ReactTestInstance | null)
 
 This allows you to assert whether the given container element does contain another host element.
 
-## `toHaveProp()`
+### `toHaveProp()`
 
 ```ts
 expect(element).toHaveProp(name: string, value?: unknown)

From 2f4741d8ca892302daa222c993de016abf64512d Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Thu, 21 Sep 2023 11:16:55 +0200
Subject: [PATCH 04/18] docs: tweaks

---
 website/docs/JestMatchers.md | 101 ++++++++++++++++++++++++++---------
 website/docs/Queries.md      |  19 +++----
 2 files changed, 85 insertions(+), 35 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 037458fa0..22f743c29 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -15,40 +15,84 @@ import TOCInline from '@theme/TOCInline';
 expect(element).toBeOnTheScreen()
 ```
 
-This allows you to assert whether element is in the element tree or not.
+This allows you to assert whether element is attached to the element tree or not. If you hold a reference to an element and it gets unmounted during the test it will no longer pass this assertion.
 
-:::note
-This matchers requires element to be attached to the element tree. This might be useful if your holding a reference to an element and the element gets unmounted during the test.
-:::
-
-## Element State
+## Element Content
 
 ### `toHaveTextContent()`
 
 ```ts
-expect(element).toHaveTextContent(text: TextMatch, options?: TextMatchOptions)
+expect(element).toHaveTextContent(t
+  text: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
 ```
 
-This allows you to assert whether the given element has a text content or not. It accepts either `string` or `RegExp` matchers, as well as `TextMatchOptions`.
+This allows you to assert whether the given element has a text content or not. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
 When `text` parameter is `undefined` it will only check for existence of text content, and when `text` is defined it will check if the actual text content matches passed value.
 
+### `toContainElement()`
+
+```ts
+expect(container).toContainElement(
+  element: ReactTestInstance | null,
+)
+```
+
+This allows you to assert whether the given container element does contain another host element.
+
+### `toBeEmptyElement()`
+
+```ts
+expect(element).toBeEmptyElement()
+```
+
+This allows you to assert whether the given element does not have any host child elements nor text content.
+
+
+
+
+
+## Element State
+
 ### `toHaveDisplayValue()`
 
 ```ts
-expect(element).toHaveDisplayValue(value: TextMatch, options?: TextMatchOptions)
+expect(element).toHaveDisplayValue(
+  value: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
 ```
 
-This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as `TextMatchOptions`.
+This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
 ### `toHaveAccessibleValue()`
 
 ```ts
-expect(element).toHaveAccessibleValue(...)
+expect(element).toHaveAccessibleValue(
+  value: {
+    min?: number;
+    max?: number;
+    now?: number;
+    text?: string | RegExp;
+  },
+)
 ```
 
 This allows you to assert whether the given element has specified accessible value.
 
+This matcher will assert accessibility value based on `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` and `accessibilityValue` props. Only defined value entires will be used in the assertion,  the element might have additional accessibility value entries and still be matched.
+
+When querying by `text` entry a string or `RegExp` might be used.
+
+
 ### `toBeEnabled()` / `toBeDisabled`
 
 ```ts
@@ -59,7 +103,7 @@ expect(element).toBeDisabled()
 These allows you to assert whether the given element is enabled or disabled from user's perspective. It relies on accessibility disabled state as set by `aria-disabled` or `accessibilityState.disabled` props. It will considers given element disabled when it or any of its ancestors is disabled.
 
 :::note
-This matchers are direct negation of each other, and both are probivided to avoid double negations in your assertions.
+This matchers are negation of each other, and both are probivided to avoid double negations in your assertions.
 :::
 
 
@@ -96,7 +140,7 @@ expect(element).toBeCollapsed()
 These allows you to assert whether the given element is expanded or collapsed from user's perspective. It relies on accessibility disabled state as set by `aria-expanded` or `accessibilityState.expanded` props.
 
 :::note
-This matchers are direct negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both with fail for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
+This matchers are negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both won't pass for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
 :::
 
 
@@ -123,35 +167,40 @@ The element is considered invisibile when it or any of its ancestors has `displa
 ### `toHaveStyle()`
 
 ```ts
-expect(element).toHaveStyle(style: StyleProp<Style>)
+expect(element).toHaveStyle(
+  style: StyleProp<Style>,
+)
 ```
 
 This allows you to assert whether the given element has given styles. 
 
-
 ## Other
 
-### `toBeEmptyElement()`
+### `toHaveAccessibleName()`
 
 ```ts
-expect(element).toBeEmptyElement()
+expect(element).toHaveAccessibleName(
+  name?: string | RegExp,
+  options?: {
+    exact?: boolean;
+    normalizer?: (text: string) => string;
+  },
+)
 ```
 
-This allows you to assert whether the given element does not have any host child elements nor text content.
+This allows you to assert whether the given element has specified accessible name. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
+Accessible name will be computed based on `aria-labelledby`, `accessibilityLabelledBy`, `aria-label`, `accessibilityLabel` props, in the absence of these props, element text content will be used.
 
-### `toContainElement()`
-
-```ts
-expect(container).toContainElement(element: ReactTestInstance | null)
-```
-
-This allows you to assert whether the given container element does contain another host element.
+When `name` parameter is `undefined` it will only check if element has any accessible name.
 
 ### `toHaveProp()`
 
 ```ts
-expect(element).toHaveProp(name: string, value?: unknown)
+expect(element).toHaveProp(
+  name: string,
+  value?: unknown,
+)
 ```
 
 This allows you to assert whether the given element has a given prop. When `value` parameter is `undefined` it will only check for existence of prop, and when `value` is defined it will check if the actual value matches passed value.
diff --git a/website/docs/Queries.md b/website/docs/Queries.md
index 462752d29..a17407392 100644
--- a/website/docs/Queries.md
+++ b/website/docs/Queries.md
@@ -184,7 +184,7 @@ getByDisplayValue(
     exact?: boolean;
     normalizer?: (text: string) => string;
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -208,7 +208,7 @@ getByTestId(
     exact?: boolean;
     normalizer?: (text: string) => string;
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -236,7 +236,7 @@ getByLabelText(
     exact?: boolean;
     normalizer?: (text: string) => string;
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -264,7 +264,7 @@ getByHintText(
     exact?: boolean;
     normalizer?: (text: string) => string;
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -305,7 +305,7 @@ getByA11yState(
   },
   options?: {
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -367,7 +367,7 @@ getByA11yValue(
   },
   options?: {
     includeHiddenElements?: boolean;
-  }
+  },
 ): ReactTestInstance;
 ```
 
@@ -457,7 +457,8 @@ screen.getByText('Goodbye World');
 screen.getByText(/hello world/);
 ```
 
-### Precision
+### Options {#text-match-options}
+#### Precision
 
 ```typescript
 type TextMatchOptions = {
@@ -475,7 +476,7 @@ Queries that take a `TextMatch` also accept an object as the second argument tha
 
 `exact` option defaults to `true` but if you want to search for a text slice or make text matching case-insensitive you can override it. That being said we advise you to use regex in more complex scenarios.
 
-### Normalization
+#### Normalization
 
 Before running any matching logic against text, it is automatically normalized. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.
 
@@ -490,7 +491,7 @@ Specifying a value for `normalizer` replaces the built-in normalization, but you
 - `trim`: Defaults to `true`. Trims leading and trailing whitespace.
 - `collapseWhitespace`: Defaults to `true`. Collapses inner whitespace (newlines, tabs repeated spaces) into a single space.
 
-#### Normalization Examples
+##### Normalization Examples
 
 To perform a match against text without trimming:
 

From 01d5050e570adbe1cc90cbabda8f29f1cbc31b3e Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Thu, 21 Sep 2023 12:02:09 +0200
Subject: [PATCH 05/18] docs: cross references

---
 website/docs/JestMatchers.md          | 10 ++--
 website/docs/MigrationJestMatchers.md | 76 +++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 3 deletions(-)
 create mode 100644 website/docs/MigrationJestMatchers.md

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 22f743c29..7aa256bef 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -3,6 +3,10 @@ id: jest-matchers
 title: Jest Matchers
 ---
 
+This guide describes built-in Jest matchers, we recommend using these matchers as they provide more readable tests, better accessibility support and better developer experience.
+
+If you are already using legacy Jest Native matchers we have a [migration guide](MigrationJestMatchers.md) for moving to the built-in matchers.
+
 import TOCInline from '@theme/TOCInline';
 
 <TOCInline toc={toc} />
@@ -93,7 +97,7 @@ This matcher will assert accessibility value based on `aria-valuemin`, `aria-val
 When querying by `text` entry a string or `RegExp` might be used.
 
 
-### `toBeEnabled()` / `toBeDisabled`
+### `toBeEnabled()` / `toBeDisabled` {#tobeenabled}
 
 ```ts
 expect(element).toBeEnabled()
@@ -116,7 +120,7 @@ expect(element).toBeSelected()
 This allows you to assert whether the given element is selected from user's perspective. It relies on accessibility selected state as set by `aria-selected` or `accessibilityState.selected` props.
 
 
-### `toBeChecked()` / `toBePartiallyChecked()`
+### `toBeChecked()` / `toBePartiallyChecked()` {#tobechecked}
 
 ```ts
 expect(element).toBeChecked()
@@ -130,7 +134,7 @@ These allows you to assert whether the given element is checked or partially che
 * `toBePartiallyChecked()` matchers works only on elements with `checkbox` role.
 :::
 
-### `toBeExpanded()` /  `toBeCollapsed()`
+### `toBeExpanded()` /  `toBeCollapsed()` {#tobeexpanded}
 
 ```ts
 expect(element).toBeExpanded()
diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
new file mode 100644
index 000000000..1bcb75915
--- /dev/null
+++ b/website/docs/MigrationJestMatchers.md
@@ -0,0 +1,76 @@
+---
+id: migration-jest-native
+title: Migration from Jest Native matchers
+---
+
+This guide describes steps necessary to migrate from [legacy Jest Native matchers](https://github.com/testing-library/jest-native) `v5` to [built-in Jest matchers](JestMatchers.md). 
+
+import TOCInline from '@theme/TOCInline';
+
+<TOCInline toc={toc} />
+
+## General notes
+
+All of built-in Jest matchers provided by React Native Testing Library are supporting only host elements. This should not be an issue, as all RNTL v12 queries already return only host elements. When this guide states that given matcher should work the same it assumes behavior only only host elements. If you need to assert status of composite elements use Jest Native matchers in [legacy mode](#gradual-migration).
+
+## Usage 
+
+You can use the built-in matchers by adding following line to your `jest-setup.ts` file:
+
+```ts
+import '@testing-library/react-native/extend-expect';
+```
+
+### Gradual migration
+
+You can use the built-in matchers alongside with legacy Jest Native matchers by chaning their import in your `jest-setup.ts` file:
+
+```ts
+// Replace this:
+// import '@testing-library/jest-native/extend-expect';
+
+// With this:
+import '@testing-library/react-native/extend-expect';
+import '@testing-library/jest-native/legacy-extend-expect';
+```
+
+In such case legacy matchers will be available using `legacy_` prefix, e.g.:
+
+```ts
+expect(element).legacy_toHaveAccessibilityState({ busy: true });
+```
+
+## Migration details
+
+### Matchers not requiring changes
+
+Following matchers should work the same:
+* [`toBeEmptyElement()`](JestMatchers.md#tobeemptyelement)
+* [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled)
+* [`toBeOnTheScreen()`](JestMatchers.md#tobeonthescreen)
+* [`toBeVisible()`](JestMatchers.md#tobevisible)
+* [`toContainElement()`](JestMatchers.md#tocontainelement)
+* [`toHaveDisplayValue()`](JestMatchers.md#tohavedisplayvalue)
+* [`toHaveProp()`](JestMatchers.md#tohaveprop)
+* [`toHaveStyle()`](JestMatchers.md#tohavestyle)
+* [`toHaveTextContent()`](JestMatchers.md#tohavetextcontent)
+  
+### Renamed matchers
+
+`toHaveAccessibilityValue()` matcher has been renamed to [`toHaveAccessibleValue()`](JestMatchers.md#tohaveaccessiblevalue) but otherwise should work the same.
+
+### Removed matchers
+
+`toHaveAccessibilityState()` matcher has been replaced by following matchers:
+* enabled state: [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled)
+* checked state: [`toBeChecked()` / `toBePartiallyChecked()`](JestMatchers.md#tobechecked)
+* selected state: [`toBeSelected()`](JestMatchers.md#tobeselected)
+* expanded state: [`toBeExpanded()` / `toBeCollapsed()`](JestMatchers.md#tobeexpanded)
+* busy state: [`toBeBusy()`](JestMatchers.md#tobebusy)
+
+The new matchers support both `accessbililityState` and `aria-*` props.
+
+You should be aware of following changes:
+* [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
+* [`toBeChecked()`](JestMatchers.md#tobechecked) matcher supports only elements with `checkbox` or `radio` role
+* [`toBePartiallyChecked()`](JestMatchers.md#tobechecked) matchers supports only elements with `checkbox` role

From 1a43fc50abef6bf4fabd4b89cc75735e70efc35c Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Thu, 21 Sep 2023 12:05:38 +0200
Subject: [PATCH 06/18] docs: tweaks

---
 website/docs/JestMatchers.md          |  6 ++++-
 website/docs/MigrationJestMatchers.md | 38 +++++++++++++--------------
 2 files changed, 24 insertions(+), 20 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 7aa256bef..e38a40fff 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -3,9 +3,13 @@ id: jest-matchers
 title: Jest Matchers
 ---
 
+:::note
+Built-in Jest matchers require RNTL v12.4.0 or later.
+:::
+
 This guide describes built-in Jest matchers, we recommend using these matchers as they provide more readable tests, better accessibility support and better developer experience.
 
-If you are already using legacy Jest Native matchers we have a [migration guide](MigrationJestMatchers.md) for moving to the built-in matchers.
+If you are already using legacy Jest Native matchers we have a [migration guide](migration-jest-native) for moving to the built-in matchers.
 
 import TOCInline from '@theme/TOCInline';
 
diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 1bcb75915..34f8313ec 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -3,7 +3,7 @@ id: migration-jest-native
 title: Migration from Jest Native matchers
 ---
 
-This guide describes steps necessary to migrate from [legacy Jest Native matchers](https://github.com/testing-library/jest-native) `v5` to [built-in Jest matchers](JestMatchers.md). 
+This guide describes steps necessary to migrate from [legacy Jest Native matchers](https://github.com/testing-library/jest-native) `v5` to [built-in Jest matchers](jest-matchers). 
 
 import TOCInline from '@theme/TOCInline';
 
@@ -45,32 +45,32 @@ expect(element).legacy_toHaveAccessibilityState({ busy: true });
 ### Matchers not requiring changes
 
 Following matchers should work the same:
-* [`toBeEmptyElement()`](JestMatchers.md#tobeemptyelement)
-* [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled)
-* [`toBeOnTheScreen()`](JestMatchers.md#tobeonthescreen)
-* [`toBeVisible()`](JestMatchers.md#tobevisible)
-* [`toContainElement()`](JestMatchers.md#tocontainelement)
-* [`toHaveDisplayValue()`](JestMatchers.md#tohavedisplayvalue)
-* [`toHaveProp()`](JestMatchers.md#tohaveprop)
-* [`toHaveStyle()`](JestMatchers.md#tohavestyle)
-* [`toHaveTextContent()`](JestMatchers.md#tohavetextcontent)
+* [`toBeEmptyElement()`](jest-matchers#tobeemptyelement)
+* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled)
+* [`toBeOnTheScreen()`](jest-matchers#tobeonthescreen)
+* [`toBeVisible()`](jest-matchers#tobevisible)
+* [`toContainElement()`](jest-matchers#tocontainelement)
+* [`toHaveDisplayValue()`](jest-matchers#tohavedisplayvalue)
+* [`toHaveProp()`](jest-matchers#tohaveprop)
+* [`toHaveStyle()`](jest-matchers#tohavestyle)
+* [`toHaveTextContent()`](jest-matchers#tohavetextcontent)
   
 ### Renamed matchers
 
-`toHaveAccessibilityValue()` matcher has been renamed to [`toHaveAccessibleValue()`](JestMatchers.md#tohaveaccessiblevalue) but otherwise should work the same.
+`toHaveAccessibilityValue()` matcher has been renamed to [`toHaveAccessibleValue()`](jest-matchers#tohaveaccessiblevalue) but otherwise should work the same.
 
 ### Removed matchers
 
 `toHaveAccessibilityState()` matcher has been replaced by following matchers:
-* enabled state: [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled)
-* checked state: [`toBeChecked()` / `toBePartiallyChecked()`](JestMatchers.md#tobechecked)
-* selected state: [`toBeSelected()`](JestMatchers.md#tobeselected)
-* expanded state: [`toBeExpanded()` / `toBeCollapsed()`](JestMatchers.md#tobeexpanded)
-* busy state: [`toBeBusy()`](JestMatchers.md#tobebusy)
+* enabled state: [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled)
+* checked state: [`toBeChecked()` / `toBePartiallyChecked()`](jest-matchers#tobechecked)
+* selected state: [`toBeSelected()`](jest-matchers#tobeselected)
+* expanded state: [`toBeExpanded()` / `toBeCollapsed()`](jest-matchers#tobeexpanded)
+* busy state: [`toBeBusy()`](jest-matchers#tobebusy)
 
 The new matchers support both `accessbililityState` and `aria-*` props.
 
 You should be aware of following changes:
-* [`toBeEnabled()` / `toBeDisabled()`](JestMatchers.md#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
-* [`toBeChecked()`](JestMatchers.md#tobechecked) matcher supports only elements with `checkbox` or `radio` role
-* [`toBePartiallyChecked()`](JestMatchers.md#tobechecked) matchers supports only elements with `checkbox` role
+* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
+* [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` or `radio` role
+* [`toBePartiallyChecked()`](jest-matchers#tobechecked) matchers supports only elements with `checkbox` role

From e175f310c1e846e424173bdf54fde15ce8bade71 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 10:50:24 +0100
Subject: [PATCH 07/18] docs: tweaks

---
 website/docs/JestMatchers.md          |  4 ++--
 website/docs/MigrationJestMatchers.md | 14 +++++++++-----
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index e38a40fff..f324fe2a9 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -81,10 +81,10 @@ expect(element).toHaveDisplayValue(
 
 This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
-### `toHaveAccessibleValue()`
+### `toHaveAccessibilityValue()`
 
 ```ts
-expect(element).toHaveAccessibleValue(
+expect(element).toHaveAccessibilityValue(
   value: {
     min?: number;
     max?: number;
diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 34f8313ec..318939937 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -3,7 +3,7 @@ id: migration-jest-native
 title: Migration from Jest Native matchers
 ---
 
-This guide describes steps necessary to migrate from [legacy Jest Native matchers](https://github.com/testing-library/jest-native) `v5` to [built-in Jest matchers](jest-matchers). 
+This guide describes steps necessary to migrate from [legacy Jest Native matchers v5](https://github.com/testing-library/jest-native) to [built-in Jest matchers](jest-matchers). 
 
 import TOCInline from '@theme/TOCInline';
 
@@ -50,15 +50,12 @@ Following matchers should work the same:
 * [`toBeOnTheScreen()`](jest-matchers#tobeonthescreen)
 * [`toBeVisible()`](jest-matchers#tobevisible)
 * [`toContainElement()`](jest-matchers#tocontainelement)
+* [`toHaveAccessibilityValue()`](jest-matchers#tohaveaccessibilityvalue)
 * [`toHaveDisplayValue()`](jest-matchers#tohavedisplayvalue)
 * [`toHaveProp()`](jest-matchers#tohaveprop)
 * [`toHaveStyle()`](jest-matchers#tohavestyle)
 * [`toHaveTextContent()`](jest-matchers#tohavetextcontent)
   
-### Renamed matchers
-
-`toHaveAccessibilityValue()` matcher has been renamed to [`toHaveAccessibleValue()`](jest-matchers#tohaveaccessiblevalue) but otherwise should work the same.
-
 ### Removed matchers
 
 `toHaveAccessibilityState()` matcher has been replaced by following matchers:
@@ -70,6 +67,13 @@ Following matchers should work the same:
 
 The new matchers support both `accessbililityState` and `aria-*` props.
 
+### Added matchers
+
+Following new matchers have been added:
+* [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename)
+
+### Noteworthy details
+
 You should be aware of following changes:
 * [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
 * [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` or `radio` role

From 63ebf4a75833923bbe636d553b02f2052e826c15 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 10:55:52 +0100
Subject: [PATCH 08/18] docs: tweaks

---
 website/docs/MigrationJestMatchers.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 318939937..581e0d194 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -23,7 +23,7 @@ import '@testing-library/react-native/extend-expect';
 
 ### Gradual migration
 
-You can use the built-in matchers alongside with legacy Jest Native matchers by chaning their import in your `jest-setup.ts` file:
+You can use the built-in matchers alongside with legacy Jest Native matchers by changing their import in your `jest-setup.ts` file:
 
 ```ts
 // Replace this:
@@ -56,7 +56,7 @@ Following matchers should work the same:
 * [`toHaveStyle()`](jest-matchers#tohavestyle)
 * [`toHaveTextContent()`](jest-matchers#tohavetextcontent)
   
-### Removed matchers
+### Replaced matchers
 
 `toHaveAccessibilityState()` matcher has been replaced by following matchers:
 * enabled state: [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled)
@@ -69,8 +69,7 @@ The new matchers support both `accessbililityState` and `aria-*` props.
 
 ### Added matchers
 
-Following new matchers have been added:
-* [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename)
+New [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename) has been added.
 
 ### Noteworthy details
 

From c1d1b7b56a1f0e59cc6dde6f5d89fae5575be330 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:29:21 +0100
Subject: [PATCH 09/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index f324fe2a9..67011805f 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -111,7 +111,7 @@ expect(element).toBeDisabled()
 These allows you to assert whether the given element is enabled or disabled from user's perspective. It relies on accessibility disabled state as set by `aria-disabled` or `accessibilityState.disabled` props. It will considers given element disabled when it or any of its ancestors is disabled.
 
 :::note
-This matchers are negation of each other, and both are probivided to avoid double negations in your assertions.
+This matchers are negation of each other, and both are provided to avoid double negations in your assertions.
 :::
 
 

From e54822626d366b0b70ad469f5fbb05139ce9c4a1 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:30:17 +0100
Subject: [PATCH 10/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 67011805f..fbf39227e 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -135,7 +135,7 @@ These allows you to assert whether the given element is checked or partially che
 
 :::note
 * `toBeChecked()` matcher works only on elements with `checkbox` or `radio` role.
-* `toBePartiallyChecked()` matchers works only on elements with `checkbox` role.
+* `toBePartiallyChecked()` matcher works only on elements with `checkbox` role.
 :::
 
 ### `toBeExpanded()` /  `toBeCollapsed()` {#tobeexpanded}

From 6e65f53e20bfb8f626d9a558da1f96ce7389a05f Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:30:25 +0100
Subject: [PATCH 11/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index fbf39227e..717063226 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -30,7 +30,7 @@ This allows you to assert whether element is attached to the element tree or not
 ### `toHaveTextContent()`
 
 ```ts
-expect(element).toHaveTextContent(t
+expect(element).toHaveTextContent(
   text: string | RegExp,
   options?: {
     exact?: boolean;

From 2e356d0c387b8201bdbe71d767742dbfcd6be938 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:30:54 +0100
Subject: [PATCH 12/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 717063226..c10c6aa2d 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -148,7 +148,7 @@ expect(element).toBeCollapsed()
 These allows you to assert whether the given element is expanded or collapsed from user's perspective. It relies on accessibility disabled state as set by `aria-expanded` or `accessibilityState.expanded` props.
 
 :::note
-This matchers are negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both won't pass for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
+These matchers are negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both won't pass for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
 :::
 
 

From 18b4227022b7841b0fdf97dab284b0f875a1fbf3 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:31:04 +0100
Subject: [PATCH 13/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index c10c6aa2d..75a0d9902 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -214,5 +214,5 @@ expect(element).toHaveProp(
 This allows you to assert whether the given element has a given prop. When `value` parameter is `undefined` it will only check for existence of prop, and when `value` is defined it will check if the actual value matches passed value.
 
 :::note
-This matchers should be treated as escape hatch to be used when all other matchers are not suitable.
+This matcher should be treated as an escape hatch to be used when all other matchers are not suitable.
 :::
\ No newline at end of file

From b7d00867173886b147e5421c3bc5c04755b7d662 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:31:12 +0100
Subject: [PATCH 14/18] Update website/docs/JestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/JestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 75a0d9902..75aa2eee3 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -170,7 +170,7 @@ expect(element).toBeVisible()
 
 This allows you to assert whether the given element is visible from user's perspective. 
 
-The element is considered invisibile when it or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessbility.
+The element is considered invisible when itself or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessbility.
 
 ### `toHaveStyle()`
 

From 86317fc4b21356540edfa47f6ec2ef987cbbadb6 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:33:38 +0100
Subject: [PATCH 15/18] Update website/docs/MigrationJestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/MigrationJestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 581e0d194..6a8d320c6 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -76,4 +76,4 @@ New [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename) has been adde
 You should be aware of following changes:
 * [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
 * [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` or `radio` role
-* [`toBePartiallyChecked()`](jest-matchers#tobechecked) matchers supports only elements with `checkbox` role
+* [`toBePartiallyChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` role

From 744a0c1836882ec5d82d76f8639f68e6bd20d897 Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Wed, 8 Nov 2023 17:33:45 +0100
Subject: [PATCH 16/18] Update website/docs/MigrationJestMatchers.md

Co-authored-by: Pierre Zimmermann <64224599+pierrezimmermannbam@users.noreply.github.com>
---
 website/docs/MigrationJestMatchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 6a8d320c6..3ea05420c 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -3,7 +3,7 @@ id: migration-jest-native
 title: Migration from Jest Native matchers
 ---
 
-This guide describes steps necessary to migrate from [legacy Jest Native matchers v5](https://github.com/testing-library/jest-native) to [built-in Jest matchers](jest-matchers). 
+This guide describes the steps necessary to migrate from [legacy Jest Native matchers v5](https://github.com/testing-library/jest-native) to [built-in Jest matchers](jest-matchers). 
 
 import TOCInline from '@theme/TOCInline';
 

From e1fa4e4147f2ce9cd4535740db37885ca30fb07e Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Thu, 9 Nov 2023 16:29:30 +0100
Subject: [PATCH 17/18] docs: spellchecking

---
 README.md                             | 20 ++++++------
 website/docs/JestMatchers.md          | 46 +++++++++++++--------------
 website/docs/MigrationJestMatchers.md | 20 ++++++------
 3 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index dd89dd711..18141b520 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@
 
 ## 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.
+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 tests 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
 
@@ -50,7 +50,7 @@ This library has a `peerDependencies` listing for `react-test-renderer`. Make su
 
 ### Additional Jest matchers
 
-In order to use additional React Native-specific jest matchers from [@testing-library/jest-native](https://github.com/testing-library/jest-native) package add it to your project:
+To use additional 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`
 
@@ -64,7 +64,7 @@ yarn add --dev @testing-library/jest-native
 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.json` file):
+Then automatically add it to your jest tests by using the `setupFilesAfterEnv` option in your Jest configuration (it's usually located either in `package.json` under the `"jest"` key or in a `jest.config.json` file):
 
 ```json
 {
@@ -75,9 +75,9 @@ Then automatically add it to your jest tests by using `setupFilesAfterEnv` optio
 
 ### Custom Jest Preset (React Native before 0.71)
 
-We generally advise to use the "react-native" preset when testing with this library.
+We generally advise using the "react-native" preset when testing with this library.
 
-However, if you use React Native version earlier than 0.71 with [modern Jest fake timers](https://jestjs.io/blog/2020/05/05/jest-26#new-fake-timers) (default since Jest 27), you'll need to apply this custom Jest preset or otherwise awaiting promises, like using `waitFor` or `findBy*`, queries will fail with timeout.
+However, if you use React Native version earlier than 0.71 with [modern Jest fake timers](https://jestjs.io/blog/2020/05/05/jest-26#new-fake-timers) (default since Jest 27), you'll need to apply this custom Jest preset or otherwise awaiting promises, like using `waitFor` or `findBy*`, queries will fail with a timeout.
 
 This is a [known issue](https://github.com/facebook/react-native/issues/29303). It happens because React Native's Jest preset overrides native Promise. Our preset restores it to defaults, which is not a problem in most apps out there.
 
@@ -130,11 +130,11 @@ You can find the source of `QuestionsBoard` component and this example [here](ht
 
 The [public API](https://callstack.github.io/react-native-testing-library/docs/api) of `@testing-library/react-native` is focused around these essential methods:
 
-- [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) – deeply renders given React element and returns helpers to query the output components.
+- [`render`](https://callstack.github.io/react-native-testing-library/docs/api#render) – deeply renders the given React element and returns helpers to query the output components.
 - [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/api#fireevent) - invokes named event handler on the element.
-- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/api#waitfor) - waits for non-deterministic periods of time until queried element is added or times out.
-- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/api#waitforelementtoberemoved) - waits for non-deterministic periods of time until queried element is removed or times out.
-- [`within`](https://callstack.github.io/react-native-testing-library/docs/api#within) - creates a queries object scoped for given element.
+- [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/api#waitfor) - waits for non-deterministic periods of time until the queried element is added or times out.
+- [`waitForElementToBeRemoved`](https://callstack.github.io/react-native-testing-library/docs/api#waitforelementtoberemoved) - waits for non-deterministic periods of time until the queried element is removed or times out.
+- [`within`](https://callstack.github.io/react-native-testing-library/docs/api#within) - creates a queries object scoped for a given element.
 
 ## Migration Guides
 
@@ -150,7 +150,7 @@ The [public API](https://callstack.github.io/react-native-testing-library/docs/a
 
 ## Related External Resources
 
-- [Real world extensive examples repo](https://github.com/vanGalilea/react-native-testing)
+- [Real-world extensive examples repo](https://github.com/vanGalilea/react-native-testing)
 - [Where and how to start testing 🧪 your react-native app ⚛️ and how to keep on testin’](https://blog.usejournal.com/where-and-how-to-start-testing-your-react-native-app-%EF%B8%8F-and-how-to-keep-on-testin-ec3464fb9b41)
 - [Intro to React Native Testing Library & Jest Native](https://youtu.be/CpTQb0XWlRc)
 
diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 75aa2eee3..32a4d76e8 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -7,7 +7,7 @@ title: Jest Matchers
 Built-in Jest matchers require RNTL v12.4.0 or later.
 :::
 
-This guide describes built-in Jest matchers, we recommend using these matchers as they provide more readable tests, better accessibility support and better developer experience.
+This guide describes built-in Jest matchers, we recommend using these matchers as they provide more readable tests, better accessibility support, and a better developer experience.
 
 If you are already using legacy Jest Native matchers we have a [migration guide](migration-jest-native) for moving to the built-in matchers.
 
@@ -23,7 +23,7 @@ import TOCInline from '@theme/TOCInline';
 expect(element).toBeOnTheScreen()
 ```
 
-This allows you to assert whether element is attached to the element tree or not. If you hold a reference to an element and it gets unmounted during the test it will no longer pass this assertion.
+This allows you to assert whether an element is attached to the element tree or not. If you hold a reference to an element and it gets unmounted during the test it will no longer pass this assertion.
 
 ## Element Content
 
@@ -39,9 +39,9 @@ expect(element).toHaveTextContent(
 )
 ```
 
-This allows you to assert whether the given element has a text content or not. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
+This allows you to assert whether the given element has text content or not. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
-When `text` parameter is `undefined` it will only check for existence of text content, and when `text` is defined it will check if the actual text content matches passed value.
+When the `text` parameter is `undefined` it will only check for the existence of text content, and when `text` is defined it will check if the actual text content matches the passed value.
 
 ### `toContainElement()`
 
@@ -59,7 +59,7 @@ This allows you to assert whether the given container element does contain anoth
 expect(element).toBeEmptyElement()
 ```
 
-This allows you to assert whether the given element does not have any host child elements nor text content.
+This allows you to assert whether the given element does not have any host child elements or text content.
 
 
 
@@ -79,7 +79,7 @@ expect(element).toHaveDisplayValue(
 )
 ```
 
-This allows you to assert whether the given `TextInput` element has specified display value. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
+This allows you to assert whether the given `TextInput` element has a specified display value. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
 ### `toHaveAccessibilityValue()`
 
@@ -94,9 +94,9 @@ expect(element).toHaveAccessibilityValue(
 )
 ```
 
-This allows you to assert whether the given element has specified accessible value.
+This allows you to assert whether the given element has a specified accessible value.
 
-This matcher will assert accessibility value based on `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` and `accessibilityValue` props. Only defined value entires will be used in the assertion,  the element might have additional accessibility value entries and still be matched.
+This matcher will assert accessibility value based on `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` and `accessibilityValue` props. Only defined value entries will be used in the assertion,  the element might have additional accessibility value entries and still be matched.
 
 When querying by `text` entry a string or `RegExp` might be used.
 
@@ -108,10 +108,10 @@ expect(element).toBeEnabled()
 expect(element).toBeDisabled()
 ```
 
-These allows you to assert whether the given element is enabled or disabled from user's perspective. It relies on accessibility disabled state as set by `aria-disabled` or `accessibilityState.disabled` props. It will considers given element disabled when it or any of its ancestors is disabled.
+These allow you to assert whether the given element is enabled or disabled from the user's perspective. It relies on the accessibility disabled state as set by `aria-disabled` or `accessibilityState.disabled` props. It will consider a given element disabled when it or any of its ancestors is disabled.
 
 :::note
-This matchers are negation of each other, and both are provided to avoid double negations in your assertions.
+These matchers are the negation of each other, and both are provided to avoid double negations in your assertions.
 :::
 
 
@@ -121,7 +121,7 @@ This matchers are negation of each other, and both are provided to avoid double
 expect(element).toBeSelected()
 ```
 
-This allows you to assert whether the given element is selected from user's perspective. It relies on accessibility selected state as set by `aria-selected` or `accessibilityState.selected` props.
+This allows you to assert whether the given element is selected from the user's perspective. It relies on the accessibility selected state as set by `aria-selected` or `accessibilityState.selected` props.
 
 
 ### `toBeChecked()` / `toBePartiallyChecked()` {#tobechecked}
@@ -131,11 +131,11 @@ expect(element).toBeChecked()
 expect(element).toBePartiallyChecked()
 ```
 
-These allows you to assert whether the given element is checked or partially checked from user's perspective. It relies on accessibility checked state as set by `aria-checked` or `accessibilityState.checked` props.
+These allow you to assert whether the given element is checked or partially checked from the user's perspective. It relies on the accessibility checked state as set by `aria-checked` or `accessibilityState.checked` props.
 
 :::note
-* `toBeChecked()` matcher works only on elements with `checkbox` or `radio` role.
-* `toBePartiallyChecked()` matcher works only on elements with `checkbox` role.
+* `toBeChecked()` matcher works only on elements with the `checkbox` or `radio` role.
+* `toBePartiallyChecked()` matcher works only on elements with the `checkbox` role.
 :::
 
 ### `toBeExpanded()` /  `toBeCollapsed()` {#tobeexpanded}
@@ -145,10 +145,10 @@ expect(element).toBeExpanded()
 expect(element).toBeCollapsed()
 ```
 
-These allows you to assert whether the given element is expanded or collapsed from user's perspective. It relies on accessibility disabled state as set by `aria-expanded` or `accessibilityState.expanded` props.
+These allows you to assert whether the given element is expanded or collapsed from the user's perspective. It relies on the accessibility disabled state as set by `aria-expanded` or `accessibilityState.expanded` props.
 
 :::note
-These matchers are negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both won't pass for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
+These matchers are the negation of each other for expandable elements (elements with explicit `aria-expanded` or `accessibilityState.expanded` props). However, both won't pass for non-expandable elements (ones without explicit `aria-expanded` or `accessibilityState.expanded` props).
 :::
 
 
@@ -158,7 +158,7 @@ These matchers are negation of each other for expandable elements (elements with
 expect(element).toBeBusy()
 ```
 
-This allows you to assert whether the given element is busy from user's perspective. It relies on accessibility selected state as set by `aria-busy` or `accessibilityState.busy` props.
+This allows you to assert whether the given element is busy from the user's perspective. It relies on the accessibility selected state as set by `aria-busy` or `accessibilityState.busy` props.
 
 ## Element Styles
 
@@ -168,9 +168,9 @@ This allows you to assert whether the given element is busy from user's perspect
 expect(element).toBeVisible()
 ```
 
-This allows you to assert whether the given element is visible from user's perspective. 
+This allows you to assert whether the given element is visible from the user's perspective. 
 
-The element is considered invisible when itself or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessbility.
+The element is considered invisible when itself or any of its ancestors has `display: none` or `opacity: 0` styles, as well as when it's hidden from accessibility.
 
 ### `toHaveStyle()`
 
@@ -196,11 +196,11 @@ expect(element).toHaveAccessibleName(
 )
 ```
 
-This allows you to assert whether the given element has specified accessible name. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
+This allows you to assert whether the given element has a specified accessible name. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
-Accessible name will be computed based on `aria-labelledby`, `accessibilityLabelledBy`, `aria-label`, `accessibilityLabel` props, in the absence of these props, element text content will be used.
+The accessible name will be computed based on `aria-labelledby`, `accessibilityLabelledBy`, `aria-label`, and `accessibilityLabel` props, in the absence of these props, the element text content will be used.
 
-When `name` parameter is `undefined` it will only check if element has any accessible name.
+When the `name` parameter is `undefined` it will only check if the element has any accessible name.
 
 ### `toHaveProp()`
 
@@ -211,7 +211,7 @@ expect(element).toHaveProp(
 )
 ```
 
-This allows you to assert whether the given element has a given prop. When `value` parameter is `undefined` it will only check for existence of prop, and when `value` is defined it will check if the actual value matches passed value.
+This allows you to assert whether the given element has a given prop. When the `value` parameter is `undefined` it will only check for existence of the prop, and when `value` is defined it will check if the actual value matches passed value.
 
 :::note
 This matcher should be treated as an escape hatch to be used when all other matchers are not suitable.
diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 3ea05420c..962fd4a90 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -11,11 +11,11 @@ import TOCInline from '@theme/TOCInline';
 
 ## General notes
 
-All of built-in Jest matchers provided by React Native Testing Library are supporting only host elements. This should not be an issue, as all RNTL v12 queries already return only host elements. When this guide states that given matcher should work the same it assumes behavior only only host elements. If you need to assert status of composite elements use Jest Native matchers in [legacy mode](#gradual-migration).
+All of the built-in Jest matchers provided by the React Native Testing Library support only host elements. This should not be an issue, as all RNTL v12 queries already return only host elements. When this guide states that a given matcher should work the same it assumes behavior only host elements. If you need to assert the status of composite elements use Jest Native matchers in [legacy mode](#gradual-migration).
 
 ## Usage 
 
-You can use the built-in matchers by adding following line to your `jest-setup.ts` file:
+You can use the built-in matchers by adding the following line to your `jest-setup.ts` file:
 
 ```ts
 import '@testing-library/react-native/extend-expect';
@@ -23,7 +23,7 @@ import '@testing-library/react-native/extend-expect';
 
 ### Gradual migration
 
-You can use the built-in matchers alongside with legacy Jest Native matchers by changing their import in your `jest-setup.ts` file:
+You can use the built-in matchers alongside legacy Jest Native matchers by changing their import in your `jest-setup.ts` file:
 
 ```ts
 // Replace this:
@@ -34,7 +34,7 @@ import '@testing-library/react-native/extend-expect';
 import '@testing-library/jest-native/legacy-extend-expect';
 ```
 
-In such case legacy matchers will be available using `legacy_` prefix, e.g.:
+In this case legacy matchers will be available using the `legacy_` prefix, e.g.:
 
 ```ts
 expect(element).legacy_toHaveAccessibilityState({ busy: true });
@@ -44,7 +44,7 @@ expect(element).legacy_toHaveAccessibilityState({ busy: true });
 
 ### Matchers not requiring changes
 
-Following matchers should work the same:
+The following matchers should work the same:
 * [`toBeEmptyElement()`](jest-matchers#tobeemptyelement)
 * [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled)
 * [`toBeOnTheScreen()`](jest-matchers#tobeonthescreen)
@@ -58,14 +58,14 @@ Following matchers should work the same:
   
 ### Replaced matchers
 
-`toHaveAccessibilityState()` matcher has been replaced by following matchers:
+The `toHaveAccessibilityState()` matcher has been replaced by the following matchers:
 * enabled state: [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled)
 * checked state: [`toBeChecked()` / `toBePartiallyChecked()`](jest-matchers#tobechecked)
 * selected state: [`toBeSelected()`](jest-matchers#tobeselected)
 * expanded state: [`toBeExpanded()` / `toBeCollapsed()`](jest-matchers#tobeexpanded)
 * busy state: [`toBeBusy()`](jest-matchers#tobebusy)
 
-The new matchers support both `accessbililityState` and `aria-*` props.
+The new matchers support both `accessibilityState` and `aria-*` props.
 
 ### Added matchers
 
@@ -73,7 +73,7 @@ New [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename) has been adde
 
 ### Noteworthy details
 
-You should be aware of following changes:
-* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself
-* [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` or `radio` role
+You should be aware of the following details:
+* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself. This is the same as in legacy Jest Native Matchers but differs from the removed `toHaveAccessibilityState()` matcher.
+* [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with a `checkbox` or `radio` role
 * [`toBePartiallyChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` role

From 7f272dd7a16dca0c9b25d340c792acc3dec0d6fb Mon Sep 17 00:00:00 2001
From: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Date: Thu, 9 Nov 2023 17:06:09 +0100
Subject: [PATCH 18/18] chore: final fixes

---
 website/docs/JestMatchers.md          | 4 +---
 website/docs/MigrationJestMatchers.md | 2 +-
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index 32a4d76e8..36bb5d4ca 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -39,9 +39,7 @@ expect(element).toHaveTextContent(
 )
 ```
 
-This allows you to assert whether the given element has text content or not. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
-
-When the `text` parameter is `undefined` it will only check for the existence of text content, and when `text` is defined it will check if the actual text content matches the passed value.
+This allows you to assert whether the given element has the given text content or not. It accepts either `string` or `RegExp` matchers, as well as [text match options](Queries.md#text-match-options) of `exact` and `normalizer`.
 
 ### `toContainElement()`
 
diff --git a/website/docs/MigrationJestMatchers.md b/website/docs/MigrationJestMatchers.md
index 962fd4a90..e38115263 100644
--- a/website/docs/MigrationJestMatchers.md
+++ b/website/docs/MigrationJestMatchers.md
@@ -74,6 +74,6 @@ New [`toHaveAccessibleName()`](jest-matchers#tohaveaccessiblename) has been adde
 ### Noteworthy details
 
 You should be aware of the following details:
-* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for element ancestors and not only the element itself. This is the same as in legacy Jest Native Matchers but differs from the removed `toHaveAccessibilityState()` matcher.
+* [`toBeEnabled()` / `toBeDisabled()`](jest-matchers#tobeenabled) matchers also check the disabled state for the element's ancestors and not only the element itself. This is the same as in legacy Jest Native matchers of the same name but differs from the removed `toHaveAccessibilityState()` matcher.
 * [`toBeChecked()`](jest-matchers#tobechecked) matcher supports only elements with a `checkbox` or `radio` role
 * [`toBePartiallyChecked()`](jest-matchers#tobechecked) matcher supports only elements with `checkbox` role