From cc0d1c5b4092a1591c1beff36964b8f736a245a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 27 Dec 2023 14:04:31 +0100
Subject: [PATCH 1/3] docs: add jsdocs for jest matchers

---
 src/matchers/types.ts | 248 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 247 insertions(+), 1 deletion(-)

diff --git a/src/matchers/types.ts b/src/matchers/types.ts
index 78a85b886..168fcf4d9 100644
--- a/src/matchers/types.ts
+++ b/src/matchers/types.ts
@@ -6,26 +6,272 @@ import { Style } from './to-have-style';
 
 export interface JestNativeMatchers<R> {
   /**
-   * Assert whether an element is present in the element tree or not.
+   * Assert whether a host element is present in the element tree (screen) or not.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeonthescreen)
+   *
+   * @example
+   * <Text>Hello</Text>
+   *
+   * expect(getByText('Hello')).toBeOnTheScreen()
+   * expect(queryByText('Other')).not.toBeOnTheScreen()
    */
   toBeOnTheScreen(): R;
 
+  /**
+   * Assert whether a host element is checked based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobechecked)
+   *
+   * @see {@link toBePartiallyChecked} for a related matcher.
+   *
+   * @example
+   * <View accessible role="checkbox" aria-checked aria-label="Enable" />
+   *
+   * expect(getByRole('checkbox', { name: "Enable" })).toBeChecked()
+   */
   toBeChecked(): R;
+
+  /**
+   * Assert whether a host element is collapsed based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeexpanded)
+   *
+   * @see {@link toBeExpanded} for an inverse matcher.
+   *
+   * @example
+   * <View testID="details" aria-expanded={false} />
+   *
+   * expect(getByTestId('details').toBeCollapsed()
+   */
   toBeCollapsed(): R;
+
+  /**
+   * Assert whether a host element is disabled based on accessibility props.
+   *
+   * This matcher will check ancestor elements for their disabled state as well.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeenabled)
+   *
+   * @see {@link toBeEnabled} for an inverse matcher.
+   *
+   * @example
+   * <View role="button" aria-disabled />
+   *
+   * expect(getByRole('button').toBeDisabled()
+   *
+   */
   toBeDisabled(): R;
+
+  /**
+   * Assert whether a host element is busy based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobebusy)
+   *
+   * @example
+   * <View testID="loader" aria-busy />
+   *
+   * expect(getByTestId('loader')).toBeBusy()
+   */
   toBeBusy(): R;
+
+  /**
+   * Assert whether a host element has no host children or text content.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeemptyelement)
+   *
+   * @example
+   * <View testID="not-empty">
+   *   <View testID="empty" />
+   * </View>
+   *
+   * expect(getByTestId('empty')).toBeEmptyElement()
+   * expect(getByTestId('not-mepty')).not.toBeEmptyElement()
+   */
   toBeEmptyElement(): R;
+
+  /**
+   * Assert whether a host element is enabled based on accessibility props.
+   *
+   * This matcher will check ancestor elements for their enabled state as well.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeenabled)
+   *
+   * @see {@link toBeDisabled} for inverse matcher.
+   *
+   * @example
+   * <View role="button" aria-disabled={false} />
+   *
+   * expect(getByRole('button').toBeEnabled()
+   */
   toBeEnabled(): R;
+
+  /**
+   * Assert whether a host element is expanded based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeexpanded)
+   *
+   * @see {@link toBeCollapsed} for inverse matcher.
+   *
+   * @example
+   * <View testID="details" aria-expanded />
+   *
+   * expect(getByTestId('details').toBeExpanded()
+   */
   toBeExpanded(): R;
+
+  /**
+   * Assert whether a host element is partially checked based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobechecked)
+   *
+   * @see {@link toBeChecked} for related matcher.
+   *
+   * @example
+   * <View accessible role="checkbox" aria-checked="mixed" aria-label="Enable" />
+   *
+   * expect(getByRole('checkbox', { name: "Enable" })).toBePartiallyChecked()
+   */
   toBePartiallyChecked(): R;
+
+  /**
+   * Assert whether a host element is selected based on accessibility props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeselected)
+   *
+   * @example
+   * <View testID="view" aria-selected />
+   *
+   * expect(getByTestId('view')).toBeSelected()
+   */
   toBeSelected(): R;
+
+  /**
+   * Assert whether a host element is visible based on style and accessibility props.
+   *
+   * This matcher will check ancestor elements for their visibility as well.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobevisible)
+   *
+   * @example
+   * <View testID="visible" />
+   * <View testID="not-visible" style={{ display: 'none' }} />
+   *
+   * expect(getByTestId('visible')).toBeVisible()
+   * expect(getByTestId('not-visible')).not.toBeVisible()
+   */
   toBeVisible(): R;
+
+  /**
+   * Assert whether a host element contains another host element.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tocontainelement)
+   *
+   * @example
+   * <View testID="outer">
+   *   <View testID="inner" />
+   * </View>
+   *
+   * expect(getByTestId('outer')).toContainElement(getByTestId('inner'));
+   */
   toContainElement(element: ReactTestInstance | null): R;
+
+  /**
+   * Assert whether a host element has a given accessbility value.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveaccessibilityvalue)
+   *
+   *
+   * @example
+   * <View testID="view" aria-valuetext="33%" />
+   *
+   * expect(getByTestId('view')).toHaveAccessibilityValue({ text: '33%' });
+   */
   toHaveAccessibilityValue(expectedValue: AccessibilityValueMatcher): R;
+
+  /**
+   * Assert whether a host element has a given accessibile name based on the accessibility label or text content.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveaccessiblename)
+   *
+   * @example
+   * <View testID="view" aria-label="Hello" />
+   *
+   * expect(getByTestId('view')).toHaveAccessibleName('Hello');
+   */
   toHaveAccessibleName(expectedName?: TextMatch, options?: TextMatchOptions): R;
+
+  /**
+   * Assert whether a host `TextInput` element has a given display value based on `value` and `defaultValue` props.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavedisplayvalue)
+   *
+   * @example
+   * <TextInput testID="input" value="Hello" />
+   *
+   * expect(getByTestId('input')).toHaveDisplayValue('Hello');
+   */
   toHaveDisplayValue(expectedValue: TextMatch, options?: TextMatchOptions): R;
+
+  /**
+   * Assert whether a host element has a given prop.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveprop)
+   *
+   * @example
+   * <Text testID="text" numberOfLines={1]} />
+   *
+   * expect(getByTestId('text')).toHaveProp('numberOfLines');
+   * expect(getByTestId('text')).toHaveProp('numberOfLines', 1);
+   */
   toHaveProp(name: string, expectedValue?: unknown): R;
+
+  /**
+   * Assert whether a host element has a given style.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavestyle)
+   *
+   * @example
+   * <View testID="view" style={{ width: '100%' }} />
+   *
+   * expect(getByTestId('view')).toHaveStyle({ width: '100%' });
+   * expect(getByTestId('view')).not.toHaveStyle({ width: '50%' });
+   */
   toHaveStyle(style: StyleProp<Style>): R;
+
+  /**
+   * Assert whether a host element has a given text content.
+   *
+   * @see
+   * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavetextcontent)
+   *
+   * @example
+   * <View testID="view">
+   *   <Text>Hello World</Text>
+   * </View>
+   *
+   * expect(getByTestId('view')).toHaveTextContent('Hello World');
+   * expect(getByTestId('view')).toHaveTextContent('Hello', { exact: false }});
+   * expect(getByTestId('view')).toHaveTextContent(/hello/i);
+   * expect(getByTestId('view')).not.toHaveTextContent('Hello');
+   */
   toHaveTextContent(expectedText: TextMatch, options?: TextMatchOptions): R;
 }
 

From 7d37da8752454411c5a816d501b2d3a1d59529b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 27 Dec 2023 14:04:54 +0100
Subject: [PATCH 2/3] docs: fix formatting issues

---
 website/docs/JestMatchers.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/website/docs/JestMatchers.md b/website/docs/JestMatchers.md
index efea8a09f..54c9216c9 100644
--- a/website/docs/JestMatchers.md
+++ b/website/docs/JestMatchers.md
@@ -144,10 +144,9 @@ expect(element).toBePartiallyChecked();
 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 the `checkbox` or `radio` role.
 - `toBePartiallyChecked()` matcher works only on elements with the `checkbox` role.
-  :::
+:::
 
 ### `toBeExpanded()` / `toBeCollapsed()` {#tobeexpanded}
 

From 58de7bbdca48fcedd8c709eb3b1ddc4c63db68d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Wed, 27 Dec 2023 14:07:44 +0100
Subject: [PATCH 3/3] docs: tweaks

---
 src/matchers/types.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/matchers/types.ts b/src/matchers/types.ts
index 168fcf4d9..7a9a27b9a 100644
--- a/src/matchers/types.ts
+++ b/src/matchers/types.ts
@@ -70,6 +70,8 @@ export interface JestNativeMatchers<R> {
   /**
    * Assert whether a host element is busy based on accessibility props.
    *
+   * This matcher will check ancestor elements for their disabled state as well.
+   *
    * @see
    * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobebusy)
    *
@@ -99,7 +101,7 @@ export interface JestNativeMatchers<R> {
   /**
    * Assert whether a host element is enabled based on accessibility props.
    *
-   * This matcher will check ancestor elements for their enabled state as well.
+   * This matcher will check ancestor elements for their disabled state as well.
    *
    * @see
    * [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeenabled)