docs(react): writing tests with testing-library (#2861)

Author: sean-perkins

docs/react/testing.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: Introduction
+title: Ionic React Testing Introduction
+description: Learn how to test an Ionic React application. This document provides an overview of how to test an application built with @ionic/react.
+---
+
+# Testing Ionic React
+
+This document provides an overview of how to test an application built with `@ionic/react`. It covers the basics of testing with React, as well as the specific tools and libraries developers can use to test their applications.
+
+## Introduction
+
+Testing is an important part of the development process, and it helps to ensure that an application is working as intended. In `@ionic/react`, testing is done using a combination of tools and libraries, including Jest, React Testing Library, Playwright or Cypress.
+
+## Types of Tests
+
+There are two types of tests that can be written:
+
+**Unit Tests**: Unit tests are used to test individual functions and components in isolation. [Jest](https://jestjs.io) and [React Testing Library](https://testing-library.com) are commonly used for unit testing.
+
+**Integration Tests**: Integration tests are used to test how different components work together. [Cypress](https://www.cypress.io) or [Playwright](https://playwright.dev) are commonly used for integration testing.

docs/react/testing/introduction.md

@@ -0,0 +1,51 @@
+---
+sidebar_label: Best Practices
+---
+
+# Best Practices
+
+## IonApp is required for test templates
+
+In your test template when rendering with React Testing Library, you must wrap your component with an `IonApp` component. This is required for the component to be rendered correctly.
+
+```tsx title="Example.test.tsx"
+import { IonApp } from '@ionic/react';
+import { render } from "@testing-library/react";
+
+import Example from './Example';
+
+test('example', () => {
+  render(
+    <IonApp>
+      <Example />
+    </IonApp>
+  );
+  ...
+});
+```
+
+## Use `user-event` for user interactions
+
+React Testing Library recommends using the `user-event` library for simulating user interactions. This library provides a more realistic simulation of user interactions than the `fireEvent` function provided by React Testing Library.
+
+```tsx title="Example.test.tsx"
+import { IonApp } from '@ionic/react';
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import Example from './Example';
+
+test('example', async () => {
+  const user = userEvent.setup();
+
+  render(
+    <IonApp>
+      <Example />
+    </IonApp>
+  );
+
+  await user.click(screen.getByRole('button', { name: /click me!/i }));
+});
+```
+
+For more information on `user-event`, see the [user-event documentation](https://testing-library.com/docs/user-event/intro/).

docs/react/testing/unit-testing/best-practices.md

@@ -0,0 +1,112 @@
+---
+sidebar_label: Examples
+title: Ionic React Testing Examples
+description: Learn how to test an Ionic React application. This document provides examples of how to test different types of components.
+---
+
+# Examples
+
+## Testing a modal presented from a trigger
+
+This example shows how to test a modal that is presented from a trigger. The modal is presented when the user clicks a button.
+
+### Example component
+
+```tsx title="src/Example.tsx"
+import { IonButton, IonModal } from '@ionic/react';
+
+export default function Example() {
+  return (
+    <>
+      <IonButton id="open-modal">Open</IonButton>
+      <IonModal trigger="open-modal">Modal content</IonModal>
+    </>
+  );
+}
+```
+
+### Testing the modal
+
+```tsx title="src/Example.test.tsx"
+import { IonApp } from '@ionic/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+import Example from './Example';
+
+test('button presents a modal when clicked', async () => {
+  render(
+    <IonApp>
+      <Example />
+    </IonApp>
+  );
+  // Simulate a click on the button
+  fireEvent.click(screen.getByText('Open'));
+  // Wait for the modal to be presented
+  await waitFor(() => {
+    // Assert that the modal is present
+    expect(screen.getByText('Modal content')).toBeInTheDocument();
+  });
+});
+```
+
+## Testing a modal presented from useIonModal
+
+This example shows how to test a modal that is presented using the `useIonModal` hook. The modal is presented when the user clicks a button.
+
+### Example component
+
+```tsx title="src/Example.tsx"
+import { IonContent, useIonModal, IonHeader, IonToolbar, IonTitle, IonButton, IonPage } from '@ionic/react';
+
+const ModalContent: React.FC = () => {
+  return (
+    <IonContent>
+      <div>Modal Content</div>
+    </IonContent>
+  );
+};
+
+const Example: React.FC = () => {
+  const [present] = useIonModal(ModalContent);
+  return (
+    <IonPage>
+      <IonHeader>
+        <IonToolbar>
+          <IonTitle>Blank</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent fullscreen={true}>
+        <IonButton expand="block" className="ion-margin" onClick={() => present()}>
+          Open
+        </IonButton>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export default Example;
+```
+
+### Testing the modal
+
+```tsx title="src/Example.test.tsx"
+import { IonApp } from '@ionic/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+import Example from './Example';
+
+test('should present ModalContent when button is clicked', async () => {
+  render(
+    <IonApp>
+      <Example />
+    </IonApp>
+  );
+  // Simulate a click on the button
+  fireEvent.click(screen.getByText('Open'));
+  // Wait for the modal to be presented
+  await waitFor(() => {
+    // Assert that the modal is present
+    expect(screen.getByText('Modal Content')).toBeInTheDocument();
+  });
+});
+```

docs/react/testing/unit-testing/examples.md

@@ -0,0 +1,40 @@
+---
+sidebar_label: Setup
+title: Ionic React Unit Testing Setup
+description: Learn how to set up unit tests for an Ionic React application.
+---
+
+# Unit Testing Setup
+
+Ionic requires a few additional steps to set up unit tests. If you are using an Ionic starter project, these steps have already been completed for you.
+
+### Install React Testing Library
+
+React Testing Library is a set of utilities that make it easier to test React components. It's used to interact with components and test their behavior.
+
+```bash
+npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event
+```
+
+### Initialize Ionic React
+
+Ionic React requires the `setupIonicReact` function to be called before any tests are run. Failing to do so will result in mode-based classes and platform behaviors not being applied to your components.
+
+In `src/setupTest.ts`, add the following code:
+
+```diff
+import '@testing-library/jest-dom/extend-expect';
+
++ import { setupIonicReact } from '@ionic/react';
+
++ setupIonicReact();
+
+// Mock matchmedia
+window.matchMedia = window.matchMedia || function () {
+  return {
+    matches: false,
+    addListener: function () { },
+    removeListener: function () { }
+  };
+};
+```

docs/react/testing/unit-testing/setup.md

@@ -122,7 +122,23 @@ module.exports = {
         'react/pwa',
         'react/overlays',
         'react/storage',
-        'react/testing',
+        {
+          type: 'category',
+          label: 'Testing',
+          items: [
+            'react/testing/introduction',
+            {
+              type: 'category',
+              label: 'Unit Testing',
+              collapsed: false,
+              items: [
+                'react/testing/unit-testing/setup',
+                'react/testing/unit-testing/examples',
+                'react/testing/unit-testing/best-practices',
+              ],
+            },
+          ],
+        },
         'react/performance',
       ],
     },

sidebars.js

@@ -63,7 +63,8 @@
       "source": "/docs/vue/your-first-app/6-deploying-mobile",
       "destination": "/docs/vue/your-first-app/deploying-mobile"
     },
-    { "source": "/docs/vue/your-first-app/7-live-reload", "destination": "/docs/vue/your-first-app/live-reload" }
+    { "source": "/docs/vue/your-first-app/7-live-reload", "destination": "/docs/vue/your-first-app/live-reload" },
+    { "source": "/docs/react/testing", "destination": "/docs/react/testing/introduction" }
   ],
   "rewrites": [
     { "source": "/docs", "destination": "/" },