chore: jest matchers.

Author: mdjastrzebski

package.json

@@ -60,7 +60,9 @@
     "typescript": "^5.0.2"
   },
   "dependencies": {
-    "pretty-format": "^29.0.0"
+    "jest-matcher-utils": "^29.6.2",
+    "pretty-format": "^29.0.0",
+    "redent": "^3.0.0"
   },
   "peerDependencies": {
     "jest": ">=28.0.0",

src/matchers/__tests__/to-be-on-the-screen.test.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { render, screen } from '../..';
+import '../extend-expect';
+
+function ShowChildren({ show }: { show: boolean }) {
+  return show ? (
+    <View>
+      <Text testID="text">Hello</Text>
+    </View>
+  ) : (
+    <View />
+  );
+}
+
+test('toBeOnTheScreen() on attached element', () => {
+  render(<View testID="test" />);
+  const element = screen.getByTestId('test');
+  expect(element).toBeOnTheScreen();
+  expect(() => expect(element).not.toBeOnTheScreen())
+    .toThrowErrorMatchingInlineSnapshot(`
+    "expect(element).not.toBeOnTheScreen()
+
+    expected element tree not to contain element but found:
+      <View
+        testID="test"
+      />"
+  `);
+});
+
+test('toBeOnTheScreen() on detached element', () => {
+  render(<ShowChildren show />);
+  const element = screen.getByTestId('text');
+
+  screen.update(<ShowChildren show={false} />);
+  expect(element).toBeTruthy();
+  expect(element).not.toBeOnTheScreen();
+  expect(() => expect(element).toBeOnTheScreen())
+    .toThrowErrorMatchingInlineSnapshot(`
+    "expect(element).toBeOnTheScreen()
+
+    element could not be found in the element tree"
+  `);
+});
+
+test('toBeOnTheScreen() on null element', () => {
+  expect(null).not.toBeOnTheScreen();
+  expect(() => expect(null).toBeOnTheScreen())
+    .toThrowErrorMatchingInlineSnapshot(`
+    "expect(element).toBeOnTheScreen()
+
+    element could not be found in the element tree"
+  `);
+});
+
+test('example test', () => {
+  render(
+    <View>
+      <View testID="child" />
+    </View>
+  );
+
+  const child = screen.getByTestId('child');
+  expect(child).toBeOnTheScreen();
+
+  screen.update(<View />);
+  expect(child).not.toBeOnTheScreen();
+});

src/matchers/extend-expect.ts

@@ -0,0 +1,5 @@
+import { toBeOnTheScreen } from './to-be-on-the-screen';
+
+expect.extend({
+  toBeOnTheScreen,
+});

src/matchers/index.tsx

@@ -0,0 +1 @@
+export { toBeOnTheScreen } from './to-be-on-the-screen';

src/matchers/to-be-on-the-screen.tsx

@@ -0,0 +1,65 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { matcherHint, RECEIVED_COLOR } from 'jest-matcher-utils';
+import { checkReactElement, printElement } from './utils';
+
+export function toBeOnTheScreen(
+  this: jest.MatcherContext,
+  element: ReactTestInstance
+) {
+  if (element !== null) {
+    checkReactElement(element, toBeOnTheScreen, this);
+  }
+
+  const pass =
+    element === null ? false : getScreenRoot() === getRootElement(element);
+
+  const errorFound = () => {
+    return `expected element tree not to contain element but found:\n${printElement(
+      element
+    )}`;
+  };
+
+  const errorNotFound = () => {
+    return `element could not be found in the element tree`;
+  };
+
+  return {
+    pass,
+    message: () => {
+      return [
+        matcherHint(
+          `${this.isNot ? '.not' : ''}.toBeOnTheScreen`,
+          'element',
+          ''
+        ),
+        '',
+        RECEIVED_COLOR(this.isNot ? errorFound() : errorNotFound()),
+      ].join('\n');
+    },
+  };
+}
+
+function getRootElement(element: ReactTestInstance) {
+  let root = element;
+  while (root.parent) {
+    root = root.parent;
+  }
+  return root;
+}
+
+function getScreenRoot() {
+  try {
+    // eslint-disable-next-line import/no-extraneous-dependencies
+    const { screen } = require('@testing-library/react-native');
+    if (!screen) {
+      throw new Error('screen is undefined');
+    }
+
+    return screen.UNSAFE_root ?? screen.container;
+  } catch (error) {
+    throw new Error(
+      'Could not import `screen` object from @testing-library/react-native.\n\n' +
+        'Using toBeOnTheScreen() matcher requires @testing-library/react-native v10.1.0 or later to be added to your devDependencies.'
+    );
+  }
+}

src/matchers/utils.tsx

@@ -0,0 +1,82 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import {
+  RECEIVED_COLOR,
+  matcherHint,
+  printWithType,
+  printReceived,
+} from 'jest-matcher-utils';
+import prettyFormat, { plugins } from 'pretty-format';
+import redent from 'redent';
+
+class ReactElementTypeError extends Error {
+  constructor(
+    received: unknown,
+    matcherFn: jest.CustomMatcher,
+    context: jest.MatcherContext
+  ) {
+    super();
+
+    /* istanbul ignore next */
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, matcherFn);
+    }
+    let withType = '';
+    try {
+      withType = printWithType('Received', received, printReceived);
+    } catch (e) {
+      // Deliberately empty.
+    }
+
+    /* istanbul ignore next */
+    this.message = [
+      matcherHint(
+        `${context.isNot ? '.not' : ''}.${matcherFn.name}`,
+        'received',
+        ''
+      ),
+      '',
+      `${RECEIVED_COLOR('received')} value must be a React Element.`,
+      withType,
+    ].join('\n');
+  }
+}
+
+export function printElement(element: ReactTestInstance | null) {
+  if (element == null) {
+    return 'null';
+  }
+
+  return redent(
+    prettyFormat(
+      {
+        // This prop is needed persuade the prettyFormat that the element is
+        // a ReactTestRendererJSON instance, so it is formatted as JSX.
+        $$typeof: Symbol.for('react.test.json'),
+        type: element.type,
+        props: element.props,
+      },
+      {
+        plugins: [plugins.ReactTestComponent, plugins.ReactElement],
+        printFunctionName: false,
+        printBasicPrototype: false,
+        highlight: true,
+      }
+    ),
+    2
+  );
+}
+
+export function checkReactElement(
+  element: ReactTestInstance | null | undefined,
+  matcherFn: jest.CustomMatcher,
+  context: jest.MatcherContext
+): asserts element is ReactTestInstance {
+  if (!element) {
+    throw new ReactElementTypeError(element, matcherFn, context);
+  }
+
+  // @ts-expect-error internal _fiber property of ReactTestInstance
+  if (!element._fiber && !VALID_ELEMENTS.includes(element.type.toString())) {
+    throw new ReactElementTypeError(element, matcherFn, context);
+  }
+}

yarn.lock

@@ -4664,6 +4664,16 @@ jest-diff@^29.0.1, jest-diff@^29.6.1:
     jest-get-type "^29.4.3"
     pretty-format "^29.6.1"
 
+jest-diff@^29.6.2:
+  version "29.6.2"
+  resolved "https://registry.yarnpkg.com/jest-diff/-/jest-diff-29.6.2.tgz#c36001e5543e82a0805051d3ceac32e6825c1c46"
+  integrity sha512-t+ST7CB9GX5F2xKwhwCf0TAR17uNDiaPTZnVymP9lw0lssa9vG+AFyDZoeIHStU3WowFFwT+ky+er0WVl2yGhA==
+  dependencies:
+    chalk "^4.0.0"
+    diff-sequences "^29.4.3"
+    jest-get-type "^29.4.3"
+    pretty-format "^29.6.2"
+
 jest-docblock@^29.4.3:
   version "29.4.3"
   resolved "https://registry.yarnpkg.com/jest-docblock/-/jest-docblock-29.4.3.tgz#90505aa89514a1c7dceeac1123df79e414636ea8"
@@ -4741,6 +4751,16 @@ jest-matcher-utils@^29.0.1, jest-matcher-utils@^29.6.1:
     jest-get-type "^29.4.3"
     pretty-format "^29.6.1"
 
+jest-matcher-utils@^29.6.2:
+  version "29.6.2"
+  resolved "https://registry.yarnpkg.com/jest-matcher-utils/-/jest-matcher-utils-29.6.2.tgz#39de0be2baca7a64eacb27291f0bd834fea3a535"
+  integrity sha512-4LiAk3hSSobtomeIAzFTe+N8kL6z0JtF3n6I4fg29iIW7tt99R7ZcIFW34QkX+DuVrf+CUe6wuVOpm7ZKFJzZQ==
+  dependencies:
+    chalk "^4.0.0"
+    jest-diff "^29.6.2"
+    jest-get-type "^29.4.3"
+    pretty-format "^29.6.2"
+
 jest-message-util@^29.6.1:
   version "29.6.1"
   resolved "https://registry.yarnpkg.com/jest-message-util/-/jest-message-util-29.6.1.tgz#d0b21d87f117e1b9e165e24f245befd2ff34ff8d"
@@ -6279,6 +6299,15 @@ pretty-format@^29.0.0, pretty-format@^29.0.3, pretty-format@^29.6.1:
     ansi-styles "^5.0.0"
     react-is "^18.0.0"
 
+pretty-format@^29.6.2:
+  version "29.6.2"
+  resolved "https://registry.yarnpkg.com/pretty-format/-/pretty-format-29.6.2.tgz#3d5829261a8a4d89d8b9769064b29c50ed486a47"
+  integrity sha512-1q0oC8eRveTg5nnBEWMXAU2qpv65Gnuf2eCQzSjxpWFkPaPARwqZZDGuNE0zPAZfTCHzIk3A8dIjwlQKKLphyg==
+  dependencies:
+    "@jest/schemas" "^29.6.0"
+    ansi-styles "^5.0.0"
+    react-is "^18.0.0"
+
 process-nextick-args@~2.0.0:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/process-nextick-args/-/process-nextick-args-2.0.1.tgz#7820d9b16120cc55ca9ae7792680ae7dba6d7fe2"