@testing-library/react-native 12.1.2 → 12.2.0

package/website/docs/Troubleshooting.md

@@ -0,0 +1,44 @@
+---
+id: troubleshooting
+title: Troubleshooting
+---
+
+This guide describes common issues found by users when integrating React Native Test Library to their projects.
+
+## Matching React Native, React & React Test Renderer versions
+
+Check that you have matching versions of core dependencies:
+
+- React Native
+- React
+- React Test Renderer
+
+React Native uses different versioning scheme from React, you can use [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) to find the correct matching between React Native & React versions. In case you use Expo, you should use dependency versions recommended by them and set by `expo upgrade` command.
+
+React Test Renderer usually has same major & minor version as React, as they are closely related and React Test Renderer is part of [React monorepo](https://github.com/facebook/react).
+
+Related issues: [#1061](https://github.com/callstack/react-native-testing-library/issues/1061), [#938](https://github.com/callstack/react-native-testing-library/issues/938), [#920](https://github.com/callstack/react-native-testing-library/issues/920)
+
+Errors that might indicate that you are facing this issue:
+
+- `TypeError: Cannot read property 'current' of undefined` when calling `render()`
+- `TypeError: Cannot read property 'isBatchingLegacy' of undefined` when calling `render()`
+
+## Example repository
+
+We maintain an [example repository](https://github.com/callstack/react-native-testing-library/tree/main/examples/basic) that showcases a modern React Native Testing Library setup with TypeScript, Jest Native, etc.
+
+In case something does not work in your setup you can refer to this repository for recommended configuration.
+
+## Act warnings
+
+When writing tests you may encounter warnings connected with `act()` function. There are two kinds of these warnings:
+
+- sync `act()` warning - `Warning: An update to Component inside a test was not wrapped in act(...)`
+- async `act()` warning - `Warning: You called act(async () => ...) without await`
+
+You can read more about `act()` function in our [understanding `act` function guide](https://callstack.github.io/react-native-testing-library/docs/understanding-act).
+
+Normally, you should not encounter sync `act()` warnings, but if that happens this probably indicate an issue with your test and should be investigated.
+
+In case of async `act()` function this might happen more or less randomly, especially if your components contain async logic. So far this warning does not seem to affect test correctness.

package/website/docs/UnderstandingAct.md

@@ -0,0 +1,227 @@
+---
+id: understanding-act
+title: Understanding Act function
+---
+
+When writing RNTL tests one of the things that confuses developers the most are cryptic [`act()`](https://reactjs.org/docs/testing-recipes.html#act) function errors logged into console. In this article I will try to build an understanding of the purpose and behaviour of `act()` so you can build your tests with more confidence.
+
+## The act warnings
+
+Let’s start with typical `act()` warnings logged to console. There are two kinds of these issues, let’s call the first one the "sync `act()`" warning:
+
+```
+Warning: An update to Component inside a test was not wrapped in act(...).
+
+When testing, code that causes React state updates should be wrapped into act(...):
+
+act(() => {
+  /* fire events that update state */
+});
+/* assert on the output */
+```
+
+The second one relates to async usage of `act` so let’s call it the "async `act`" error:
+
+```
+Warning: You called act(async () => ...) without await. This could lead to unexpected
+testing behaviour, interleaving multiple act calls and mixing their scopes. You should
+- await act(async () => ...);
+```
+
+## Synchronous act
+
+### Responsibility
+
+This function is intended only for using in automated tests and works only in development mode. Attempting to use it in production build will throw an error.
+
+The responsibility for `act` function is to make React renders and updates work in tests in a similar way they work in real application by grouping and executing related units of interaction (e.g. renders, effects, etc) together.
+
+To showcase that behaviour let make a small experiment. First we define a function component that uses `useEffect` hook in a trivial way.
+
+```jsx
+function TestComponent() {
+  const [count, setCount] = React.useState(0);
+  React.useEffect(() => {
+    setCount((c) => c + 1);
+  }, []);
+
+  return <Text>Count {count}</Text>;
+}
+```
+
+In the following tests we will directly use `ReactTestRenderer` instead of RNTL `render` function to render our component for tests. In order to expose familiar queries like `getByText` we will use `within` function from RNTL.
+
+```jsx
+test('render without act', () => {
+  const renderer = TestRenderer.create(<TestComponent />);
+
+  // Bind RNTL queries for root element.
+  const view = within(renderer.root);
+  expect(view.getByText('Count 0')).toBeOnTheScreen();
+});
+```
+
+When testing without `act` call wrapping rendering call, we see that the assertion runs just after the rendering but before `useEffect`hooks effects are applied. Which is not what we expected in our tests.
+
+```jsx
+test('render with act', () => {
+  let renderer: ReactTestRenderer;
+  act(() => {
+    renderer = TestRenderer.create(<TestComponent />);
+  });
+
+  // Bind RNTL queries for root element.
+  const view = within(renderer!.root);
+  expect(view.getByText('Count 1')).toBeOnTheScreen();
+});
+```
+
+When wrapping rendering call with `act` we see that the changes caused by `useEffect` hook have been applied as we would expect.
+
+### When to use act
+
+The name `act` comes from [Arrange-Act-Assert](http://wiki.c2.com/?ArrangeActAssert) unit testing pattern. Which means it’s related to part of the test when we execute some actions on the component tree.
+
+So far we learned that `act` function allows tests to wait for all pending React interactions to be applied before we make our assertions. When using `act` we get guarantee that any state updates will be executed as well as any enqueued effects will be executed.
+
+Therefore, we should use `act` whenever there is some action that causes element tree to render, particularly:
+
+- initial render call - `ReactTestRenderer.create` call
+- re-rendering of component -`renderer.update` call
+- triggering any event handlers that cause component tree render
+
+Thankfully, for these basic cases RNTL has got you covered as our `render`, `update` and `fireEvent` methods already wrap their calls in sync `act` so that you do not have to do it explicitly.
+
+Note that `act` calls can be safely nested and internally form a stack of calls. However, overlapping `act` calls, which can be achieved using async version of `act`, [are not supported](https://github.com/facebook/react/blob/main/packages/react/src/ReactAct.js#L161).
+
+### Implementation
+
+As of React version of 18.1.0, the `act` implementation is defined in the [ReactAct.js source file](https://github.com/facebook/react/blob/main/packages/react/src/ReactAct.js) inside React repository. This implementation has been fairly stable since React 17.0.
+
+RNTL exports `act` for convenience of the users as defined in the [act.ts source file](https://github.com/callstack/react-native-testing-library/blob/main/src/act.ts). That file refers to [ReactTestRenderer.js source](https://github.com/facebook/react/blob/ce13860281f833de8a3296b7a3dad9caced102e9/packages/react-test-renderer/src/ReactTestRenderer.js#L52) file from React Test Renderer package, which finally leads to React act implementation in ReactAct.js (already mentioned above).
+
+## Asynchronous act
+
+So far we have seen synchronous version of `act` which runs its callback immediately. This can deal with things like synchronous effects or mocks using already resolved promises. However, not all component code is synchronous. Frequently our components or mocks contain some asynchronous behaviours like `setTimeout` calls or network calls. Starting from React 16.9, `act` can also be called in asynchronous mode. In such case `act` implementation checks that the passed callback returns [object resembling promise](https://github.com/facebook/react/blob/ce13860281f833de8a3296b7a3dad9caced102e9/packages/react/src/ReactAct.js#L60).
+
+### Asynchronous code
+
+Asynchronous version of `act` also is executed immediately, but the callback is not yet completed because of some asynchronous operations inside.
+
+Lets look at a simple example with component using `setTimeout` call to simulate asynchronous behaviour:
+
+```jsx
+function TestAsyncComponent() {
+  const [count, setCount] = React.useState(0);
+  React.useEffect(() => {
+    setTimeout(() => {
+      setCount((c) => c + 1);
+    }, 50);
+  }, []);
+
+  return <Text>Count {count}</Text>;
+}
+```
+
+```jsx
+test('render async natively', () => {
+  const view = render(<TestAsyncComponent />);
+  expect(view.getByText('Count 0')).toBeOnTheScreen();
+});
+```
+
+If we test our component in a native way without handling its asynchronous behaviour we will end up with sync act warning:
+
+```
+Warning: An update to TestAsyncComponent inside a test was not wrapped in act(...).
+
+When testing, code that causes React state updates should be wrapped into act(...):
+
+act(() => {
+  /* fire events that update state */
+});
+/* assert on the output */
+```
+
+Note that this is not yet the infamous async act warning. It only asks us to wrap our event code with `act` calls. However, this time our immediate state change does not originate from externally triggered events but rather forms an internal part of the component. So how can we apply `act` in such scenario?
+
+### Solution with fake timers
+
+First solution is to use Jest's fake timers inside out tests:
+
+```jsx
+test('render with fake timers', () => {
+  jest.useFakeTimers();
+  const view = render(<TestAsyncComponent />);
+
+  act(() => {
+    jest.runAllTimers();
+  });
+  expect(view.getByText('Count 1')).toBeOnTheScreen();
+});
+```
+
+That way we can wrap `jest.runAllTimers()` call which triggers the `setTimeout` updates inside an `act` call, hence resolving the act warning. Note that this whole code is synchronous thanks to usage of Jest fake timers.
+
+### Solution with real timers
+
+If we wanted to stick with real timers then things get a bit more complex. Let’s start by applying a crude solution of opening async `act()` call for the expected duration of components updates:
+
+```jsx
+test('render with real timers - sleep', async () => {
+  const view = render(<TestAsyncComponent />);
+  await act(async () => {
+    await sleep(100); // Wait a bit longer than setTimeout in `TestAsyncComponent`
+  });
+
+  expect(view.getByText('Count 1')).toBeOnTheScreen();
+});
+```
+
+This works correctly as we use an explicit async `act()` call that resolves the console error. However, it relies on our knowledge of exact implementation details which is a bad practice.
+
+Let’s try more elegant solution using `waitFor` that will wait for our desired state:
+
+```jsx
+test('render with real timers - waitFor', async () => {
+  const view = render(<TestAsyncComponent />);
+
+  await waitFor(() => view.getByText('Count 1'));
+  expect(view.getByText('Count 1')).toBeOnTheScreen();
+});
+```
+
+This also works correctly, because `waitFor` call executes async `act()` call internally.
+
+The above code can be simplified using `findBy` query:
+
+```jsx
+test('render with real timers - findBy', async () => {
+  const view = render(<TestAsyncComponent />);
+
+  expect(await view.findByText('Count 1')).toBeOnTheScreen();
+});
+```
+
+This also works since `findByText` internally calls `waitFor` which uses async `act()`.
+
+Note that all of the above examples are async tests using & awaiting async `act()` function call.
+
+### Async act warning
+
+If we modify any of the above async tests and remove `await` keyword, then we will trigger the notorious async `act()`warning:
+
+```jsx
+Warning: You called act(async () => ...) without await. This could lead to unexpected
+testing behaviour, interleaving multiple act calls and mixing their scopes. You should
+- await act(async () => ...);
+```
+
+React decides to show this error whenever it detects that async `act()`call [has not been awaited](https://github.com/facebook/react/blob/ce13860281f833de8a3296b7a3dad9caced102e9/packages/react/src/ReactAct.js#L93).
+
+The exact reasons why you might see async `act()` warnings vary, but finally it means that `act()` has been called with callback that returns `Promise`-like object, but it has not been waited on.
+
+## References
+
+- [React `act` implementation source](https://github.com/facebook/react/blob/main/packages/react/src/ReactAct.js)
+- [React testing recipes: `act()`](https://reactjs.org/docs/testing-recipes.html#act)

package/website/docs/UserEvent.md

@@ -0,0 +1,143 @@
+---
+id: user-event
+title: User Event
+---
+
+### Table of contents
+
+- [Comparison with Fire Event API](#comparison-with-fire-event-api)
+- [`setup()`](#setup)
+  - [Options](#options)
+- [`press()`](#press)
+- [`longPress()`](#longpress)
+  - [Options](#options-1)
+- [`type()`](#type)
+  - [Options](#options-2)
+  - [Sequence of events](#sequence-of-events)
+
+:::caution
+User Event API is in beta stage.
+
+This means that we plan to keep the public API signatures to remain stable, but we might introduce breaking behavioural changes, e.g. changing the ordering or timing of emitted events, without a major version update. Hopefully, well written code should not rely on such specific details.
+:::
+
+## Comparison with Fire Event API
+
+Fire Event is our original event simulation API. It offers ability to invoke **any event handler** declared on **either host or composite elements**. If the element does not have `onEventName` event handler for passed `eventName` event, or the element is disabled, Fire Event will traverse up the component tree, looking for event handler on both host and composite elements along the way. By default it will **not pass any event data**, but the user might provide it in the last argument.
+
+In contrast, User Event provides realistic event simulation for main user interactions like `press` or `type`. Each of the interactions will trigger a **sequence of events** corresponding to React Native runtime behavior. These events will be invoked **only on host elements**, and **will automatically receive event data** corresponding to each event.
+
+If User Event supports given interaction you should always prefer it over Fire Event counterpart, as it will make your tests much more realistic and hence reliable. In other cases, e.g. when event is not supported by User Event, or when invoking event handlers on composite elements, you have to use Fire Event as the only available option.
+
+## `setup()`
+
+```ts
+userEvent.setup(options?: {
+  delay: number;
+  advanceTimers: (delay: number) => Promise<void> | void;
+})
+```
+
+Example
+```ts
+const user = userEvent.setup();
+```
+
+Creates an User Event object instance which can be used to trigger events.
+
+### Options
+- `delay` - controls the default delay between subsequent events, e.g. keystrokes.
+- `advanceTimers` - time advancement utility function that should be used for fake timers. The default setup handles both real timers and Jest fake timers.
+
+
+## `press()`
+
+```ts
+press(
+  element: ReactTestInstance,
+): Promise<void>
+```
+
+Example
+```ts
+const user = userEvent.setup();
+await user.press(element);
+```
+
+This helper simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()` which is a simpler API that will only call the `onPress` prop, this function simulates the entire press interaction in a more realistic way by reproducing event sequence emitted by React Native runtime. This helper will trigger additional events like `pressIn` and `pressOut`. 
+
+## `longPress()`
+
+```ts
+longPress(
+  element: ReactTestInstance,
+  options: { duration: number } = { duration: 500 }
+): Promise<void>
+```
+
+Example
+```ts
+const user = userEvent.setup();
+await user.longPress(element);
+```
+
+Simulates a long press user interaction. In React Native the `longPress` event is emitted when the press duration exceeds long press threshold (by default 500 ms). In other aspects this actions behaves similar to regular `press` action, e.g. by emitting `pressIn` and `pressOut` events. The press duration is customisable through the options. This should be useful if you use the `delayLongPress` prop. When using real timers this will take 500 ms so it is highly recommended to use that API with fake timers to prevent test taking a long time to run. 
+
+### Options
+- `duration` - duration of the press in miliseconds. Default value is 500 ms.
+
+## `type()`
+
+```ts
+type(
+  element: ReactTestInstance,
+  text: string,
+  options?: {
+    skipPress?: boolean
+    submitEditing?: boolean
+  }
+```
+
+Example
+```ts
+const user = userEvent.setup();
+await user.type(textInput, "Hello world!");
+```
+
+This helper simulates user focusing on `TextInput` element, typing `text` one character at a time, and leaving the element.
+
+This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
+
+### Options
+ - `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
+ - `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
+
+### Sequence of events
+
+The sequence of events depends on `multiline` prop, as well as passed options.
+
+Events will not be emitted if `editable` prop is set to `false`.
+
+**Entering the element**:
+- `pressIn` (optional)
+- `focus`
+- `pressOut` (optional)
+
+The `pressIn` and `pressOut` events are sent by default, but can be skipped by passing `skipPress: true` option.
+
+**Typing (for each character)**:
+- `keyPress`
+- `textInput` (optional)
+- `change`
+- `changeText`
+- `selectionChange`
+
+The `textInput` event is sent only for mutliline text inputs.
+
+**Leaving the element**:
+- `submitEditing` (optional)
+- `endEditing`
+- `blur`
+
+The `submitEditing` event is skipped by default. It can sent by setting `submitEditing: true` option.
+

package/website/docusaurus.config.js

@@ -0,0 +1,114 @@
+const repoUrl = 'https://github.com/callstack/react-native-testing-library';
+const title = 'React Native Testing Library';
+
+const siteConfig = {
+  title, // Title for your website.
+  tagline: 'Helps you to write better tests with less effort.',
+  url: 'https://callstack.github.io', // Your website URL
+  baseUrl: '/react-native-testing-library/', // Base URL for your project
+  // The name of the GitHub repository. Used by the deployment command
+  projectName: 'react-native-testing-library',
+  organizationName: 'callstack',
+  favicon: 'img/owl.png',
+  trailingSlash: false,
+
+  themeConfig: {
+    navbar: {
+      title,
+      logo: {
+        alt: title,
+        src: 'img/owl.png',
+      },
+      items: [
+        { to: 'docs/getting-started', label: 'Docs', position: 'right' },
+        { href: repoUrl, label: 'GitHub', position: 'right' },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              key: 1,
+              label: 'Getting started',
+              to: 'docs/getting-started',
+            },
+            {
+              key: 2,
+              label: 'API',
+              to: 'docs/api',
+            },
+          ],
+        },
+        {
+          title: 'Community',
+          items: [
+            {
+              key: 3,
+              label: 'Stack Overflow',
+              href: 'http://stackoverflow.com/questions/tagged/react-native-testing-library',
+            },
+            {
+              key: 4,
+              label: 'Discord Channel',
+              href: 'https://discord.gg/QbGezWe',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              key: 5,
+              label: 'GitHub',
+              href: repoUrl,
+            },
+            {
+              key: 6,
+              label: 'Star',
+              href: repoUrl,
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Callstack Open Source`,
+    },
+    image: 'img/owl.png',
+    prism: {
+      theme: require('prism-react-renderer/themes/github'),
+      darkTheme: require('prism-react-renderer/themes/dracula'),
+      defaultLanguage: 'jsx',
+    },
+    algolia: {
+      appId: '6CJ0BV6AVN',
+      apiKey: '198ecded5a7987b04767482a8d6fe602',
+      indexName: 'crawler_React Native Testing Library Docs',
+    },
+  },
+
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          editUrl: `${repoUrl}/blob/main/website`,
+          sidebarCollapsible: false,
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          editUrl: `${repoUrl}/blob/main/blog`,
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+};
+
+module.exports = siteConfig;

package/website/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "react-native-testing-library-website",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy"
+  },
+  "dependencies": {
+    "@babel/core": "^7.11.1",
+    "@docusaurus/core": "^2.3.1",
+    "@docusaurus/preset-classic": "^2.3.1",
+    "classnames": "^2.2.6",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

package/website/sidebars.js

@@ -0,0 +1,20 @@
+module.exports = {
+  docs: {
+    Introduction: ['getting-started', 'faq'],
+    'API Reference': ['api', 'api-queries', 'user-event'],
+    Guides: [
+      'troubleshooting',
+      'how-should-i-query',
+      'eslint-plugin-testing-library',
+    ],
+    Advanced: ['testing-env', 'understanding-act'],
+    Migrations: [
+      'migration-v12',
+      'migration-v11',
+      'migration-v9',
+      'migration-v7',
+      'migration-v2',
+    ],
+    Examples: ['react-navigation', 'redux-integration'],
+  },
+};

package/website/src/components/Feature.js

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import classnames from 'classnames';
+import PropTypes from 'prop-types';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from '../css/index.module.css';
+
+export default function Feature(props) {
+  const imgUrl = useBaseUrl(props.imgUrl);
+  return (
+    <div className={classnames('col col--4', styles.feature)}>
+      {imgUrl && (
+        <div className="text--center">
+          <img
+            className={styles['feature-image']}
+            src={imgUrl}
+            alt={props.title}
+          />
+        </div>
+      )}
+
+      <h3 className={styles['feature-title']}>{props.title}</h3>
+      <p className={styles['feature-description']}>{props.description}</p>
+    </div>
+  );
+}
+
+Feature.propTypes = {
+  imgUrl: PropTypes.string,
+  title: PropTypes.string.isRequired,
+  description: PropTypes.string.isRequired,
+};

package/website/src/css/custom.css

@@ -0,0 +1,13 @@
+:root {
+  --ifm-color-primary: #bf8a65;
+  --ifm-color-primary-dark: #b67a50;
+  --ifm-color-primary-darker: #af7349;
+  --ifm-color-primary-darkest: #905f3c;
+  --ifm-color-primary-light: #c89a7a;
+  --ifm-color-primary-lighter: #cca284;
+  --ifm-color-primary-lightest: #d9b9a3;
+}
+
+.footer .footer__links {
+  margin-bottom: 3rem;
+}