@testing-library/react-native 12.1.1 → 12.1.3

package/website/docs/ReactNavigation.md

@@ -0,0 +1,371 @@
+---
+id: react-navigation
+title: React Navigation
+---
+
+This section deals with integrating `@testing-library/react-native` with `react-navigation`, using Jest.
+
+## Stack Navigator
+
+### Setting up
+
+Install the packages required for React Navigation. For this example, we will use a [stack navigator](https://reactnavigation.org/docs/stack-navigator/) to transition to the second page when any of the items are clicked on.
+
+```
+$ yarn add @react-native-community/masked-view @react-navigation/native @react-navigation/stack react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-screens
+```
+
+Create an [`./AppNavigator.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/AppNavigator.js) component which will list the navigation stack:
+
+```jsx
+import 'react-native-gesture-handler';
+import * as React from 'react';
+import { createStackNavigator } from '@react-navigation/stack';
+
+import HomeScreen from './screens/HomeScreen';
+import DetailsScreen from './screens/DetailsScreen';
+
+const { Screen, Navigator } = createStackNavigator();
+
+export default function Navigation() {
+  const options = {};
+
+  return (
+    <Navigator>
+      <Screen name="Home" component={HomeScreen} />
+      <Screen options={options} name="Details" component={DetailsScreen} />
+    </Navigator>
+  );
+}
+```
+
+Create your two screens which we will transition to and from them. The homescreen, found in [`./screens/HomeScreen.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/screens/HomeScreen.js), contains a list of elements presented in a list view. On tap of any of these items will move to the details screen with the item number:
+
+```jsx
+import * as React from 'react';
+import {
+  Text,
+  View,
+  FlatList,
+  TouchableOpacity,
+  StyleSheet,
+} from 'react-native';
+
+export default function HomeScreen({ navigation }) {
+  const [items] = React.useState(
+    new Array(20).fill(null).map((_, idx) => idx + 1)
+  );
+
+  const onOpacityPress = (item) => navigation.navigate('Details', item);
+
+  return (
+    <View>
+      <Text style={styles.header}>List of numbers from 1 to 20</Text>
+      <FlatList
+        keyExtractor={(_, idx) => `${idx}`}
+        data={items}
+        renderItem={({ item }) => (
+          <TouchableOpacity
+            onPress={() => onOpacityPress(item)}
+            style={styles.row}
+          >
+            <Text>Item number {item}</Text>
+          </TouchableOpacity>
+        )}
+      />
+    </View>
+  );
+}
+
+const divider = '#DDDDDD';
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+  row: {
+    paddingVertical: 16,
+    paddingHorizontal: 24,
+    borderBottomColor: divider,
+    borderBottomWidth: 1,
+  },
+});
+```
+
+The details screen, found in [`./screens/DetailsScreen.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/screens/DetailsScreen.js), contains a header with the item number passed from the home screen:
+
+```jsx
+// ./screens/DetailsScreen.js
+import * as React from 'react';
+import { Text, StyleSheet, View } from 'react-native';
+
+export default function DetailsScreen(props) {
+  const item = Number.parseInt(props.route.params, 10);
+
+  return (
+    <View>
+      <Text style={styles.header}>Showing details for {item}</Text>
+      <Text style={styles.body}>the number you have chosen is {item}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+  body: {
+    textAlign: 'center',
+  },
+});
+```
+
+### Setting up the test environment
+
+Install required dev dependencies:
+
+```
+$ yarn add -D jest @testing-library/react-native
+```
+
+Create your `jest.config.js` file (or place the following properties in your `package.json` as a "jest" property)
+
+```js
+module.exports = {
+  preset: 'react-native',
+  setupFiles: ['./node_modules/react-native-gesture-handler/jestSetup.js'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(jest-)?@?react-native|@react-native-community|@react-navigation)',
+
+    // For pnpm you need to use inlcude `(?!(?:.pnpm/)?` part like this:
+    // 'node_modules/(?!(?:.pnpm/)?((jest-)?@?react-native|@react-native-community|@react-navigation))',
+  ],
+};
+```
+
+Notice the 2 entries that don't come with the default React Native project:
+
+- `setupFiles` – an array of files that Jest is going to execute before running your tests. In this case, we run `react-native-gesture-handler/jestSetup.js` which sets up necessary mocks for `react-native-gesture-handler` native module
+- `transformIgnorePatterns` – an array of paths that Jest ignores when transforming code. In this case, the negative lookahead regular expression is used, to tell Jest to transform (with Babel) every package inside `node_modules/` that starts with `react-native`, `@react-native-community` or `@react-navigation` (added by us, the rest is in `react-native` preset by default, so you don't have to worry about it).
+
+### Example tests
+
+For this example, we are going to test out two things. The first thing is that the page is laid out as expected. The second, and most important, is that the page will transition to the detail screen when any item is tapped on.
+
+Let's add a [`AppNavigator.test.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/__tests__/AppNavigator.js) file in `src/__tests__` directory:
+
+```jsx
+import * as React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+import AppNavigator from '../AppNavigator';
+
+// Silence the warning https://github.com/facebook/react-native/issues/11094#issuecomment-263240420
+// Use with React Native <= 0.63
+jest.mock('react-native/Libraries/Animated/src/NativeAnimatedHelper');
+
+// Use this instead with React Native >= 0.64
+// jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper');
+
+describe('Testing react navigation', () => {
+  test('page contains the header and 10 items', async () => {
+    const component = (
+      <NavigationContainer>
+        <AppNavigator />
+      </NavigationContainer>
+    );
+
+    render(component);
+
+    const header = await screen.findByText('List of numbers from 1 to 20');
+    const items = await screen.findAllByText(/Item number/);
+
+    expect(header).toBeOnTheScreen();
+    expect(items.length).toBe(10);
+  });
+
+  test('clicking on one item takes you to the details screen', async () => {
+    const component = (
+      <NavigationContainer>
+        <AppNavigator />
+      </NavigationContainer>
+    );
+
+    render(component);
+    const toClick = await screen.findByText('Item number 5');
+
+    fireEvent(toClick, 'press');
+    const newHeader = await screen.findByText('Showing details for 5');
+    const newBody = await screen.findByText('the number you have chosen is 5');
+
+    expect(newHeader).toBeOnTheScreen();
+    expect(newBody).toBeOnTheScreen();
+  });
+});
+```
+
+## Drawer Navigator
+
+Testing the Drawer Navigation requires an additional setup step for mocking the Reanimated library.
+
+### Setting up
+
+Install the packages required for React Navigation. For this example, we will use a [drawer navigator](https://reactnavigation.org/docs/drawer-navigator/) to transition between a home screen and an additional screen.
+
+```
+$ yarn add @react-native-community/masked-view @react-navigation/native @react-navigation/drawer react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-screens
+```
+
+Create a [`./DrawerAppNavigator.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/DrawerAppNavigator.js) component which will list the navigation stack:
+
+```jsx
+import 'react-native-gesture-handler';
+import React from 'react';
+import { createDrawerNavigator } from '@react-navigation/drawer';
+
+const { Screen, Navigator } = createDrawerNavigator();
+
+export default function Navigation() {
+  return (
+    <Navigator>
+      <Screen name="Home" component={HomeScreen} />
+      <Screen name="Notifications" component={NotificationsScreen} />
+    </Navigator>
+  );
+}
+```
+
+Create your two screens which we will transition to and from:
+
+```jsx
+function HomeScreen({ navigation }) {
+  return (
+    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+      <Text>Welcome!</Text>
+      <Button
+        onPress={() => navigation.navigate('Notifications')}
+        title="Go to notifications"
+      />
+    </View>
+  );
+}
+
+function NotificationsScreen({ navigation }) {
+  return (
+    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+      <Text>This is the notifications screen</Text>
+      <Button onPress={() => navigation.goBack()} title="Go back home" />
+    </View>
+  );
+}
+```
+
+### Setting up the test environment
+
+Install required dev dependencies:
+
+```
+$ yarn add -D jest @testing-library/react-native
+```
+
+Create a [`mock file`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/jest-setup.js) necessary for your tests:
+
+```jsx
+import 'react-native-gesture-handler/jestSetup';
+
+jest.mock('react-native-reanimated', () => {
+  const Reanimated = require('react-native-reanimated/mock');
+
+  // The mock for `call` immediately calls the callback which is incorrect
+  // So we override it with a no-op
+  Reanimated.default.call = () => {};
+
+  return Reanimated;
+});
+
+// Silence the warning: Animated: `useNativeDriver` is not supported because the native animated module is missing
+jest.mock('react-native/Libraries/Animated/src/NativeAnimatedHelper');
+```
+
+Create your `jest.config.js` file (or place the following properties in your `package.json` as a "jest" property)
+
+```js
+module.exports = {
+  preset: 'react-native',
+  setupFiles: ['./jest-setup.js'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(jest-)?react-native|@react-native-community|@react-navigation)',
+  ],
+};
+```
+
+Make sure that the path to the file in `setupFiles` is correct. Jest will run these files before running your tests, so it's the best place to put your global mocks.
+
+This setup is copied from the [React Navigation documentation](https://reactnavigation.org/docs/testing/).
+
+### Example tests
+
+For this example, we are going to test out two things. The first thing is that the screen is loaded correctly. The second, and most important, is that the page will transition to the notifications screen when the button is tapped on.
+
+Let's add a [`DrawerAppNavigator.test.js`](https://github.com/callstack/react-native-testing-library/blob/main/examples/reactnavigation/src/__tests__/DrawerAppNavigator.js) file in `src/__tests__` directory:
+
+```jsx
+import React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+
+import DrawerAppNavigator from '../DrawerAppNavigator';
+
+describe('Testing react navigation', () => {
+  test('screen contains a button linking to the notifications page', async () => {
+    const component = (
+      <NavigationContainer>
+        <DrawerAppNavigator />
+      </NavigationContainer>
+    );
+
+    render(component);
+    const button = await screen.findByText('Go to notifications');
+
+    expect(button).toBeOnTheScreen();
+  });
+
+  test('clicking on the button takes you to the notifications screen', async () => {
+    const component = (
+      <NavigationContainer>
+        <DrawerAppNavigator />
+      </NavigationContainer>
+    );
+
+    render(component);
+    const oldScreen = screen.queryByText('Welcome!');
+    const button = await screen.findByText('Go to notifications');
+
+    expect(oldScreen).toBeOnTheScreen();
+
+    fireEvent(button, 'press');
+    const newScreen = await screen.findByText('This is the notifications screen');
+
+    expect(newScreen).toBeOnTheScreen();
+  });
+});
+```
+
+## Running tests
+
+To run the tests, place a test script inside your `package.json`
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+And run the `test` script with `npm test` or `yarn test`.

package/website/docs/ReduxIntegration.md

@@ -0,0 +1,137 @@
+---
+id: redux-integration
+title: Redux Integration
+---
+
+This section deals with testing RN applications developed with Redux. We will be developing a simple TODO application capable of adding and removing an item. Once included, the timestamp is included.
+
+## Setting up
+
+An example of setting up can be found [here](https://github.com/callstack/react-native-testing-library/tree/main/examples/redux).
+
+## Test cases
+
+Our test is on the components that either dispatch actions on the redux store or read some data from the redux store. This means we will test `./components/AddTodo.js` and `./components/TodoList.js`. Thus we will create `./components/AddTodo.test.js` and `./components/TodoList.test.js`
+
+For `./components/AddTodo.test.js`
+
+```jsx
+import * as React from 'react';
+import { Provider } from 'react-redux';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+import configureStore from '../store';
+import AddTodo from './AddTodo';
+
+describe('AddTodo component test', () => {
+  test('adds a new TODO when the button is pressed', () => {
+    const store = configureStore();
+
+    const component = (
+      <Provider store={store}>
+        <AddTodo />
+      </Provider>
+    );
+
+    render(component);
+
+    // There is a TextInput.
+    // https://github.com/callstack/react-native-testing-library/blob/ae3d4af370487e1e8fedd8219f77225690aefc59/examples/redux/components/AddTodo.js#L24
+    const input = screen.getByPlaceholderText(/repository/i);
+    expect(input).toBeOnTheScreen();
+
+    const textToEnter = 'This is a random element';
+    fireEvent.changeText(input, textToEnter);
+    fireEvent.press(screen.getByText('Submit form'));
+
+    const todosState = store.getState().todos;
+
+    expect(todosState.length).toEqual(1);
+
+    expect(todosState).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 1,
+          text: textToEnter,
+          date: expect.any(Date),
+        }),
+      ])
+    );
+  });
+});
+```
+
+For `./components/TodoList.test.js`
+
+```jsx
+import * as React from 'react';
+import { Provider } from 'react-redux';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+import configureStore from '../store';
+import TodoList from './TodoList';
+
+describe('TodoList component test', () => {
+  test('it should execute with a store with 4 elements', () => {
+    const initialState = {
+      todos: [
+        { id: 1, text: 'Sing something', date: new Date() },
+        { id: 2, text: 'Dance something', date: new Date() },
+        { id: 3, text: 'Sleep something', date: new Date() },
+        { id: 4, text: 'Sleep something', date: new Date() },
+      ],
+    };
+    const store = configureStore(initialState);
+
+    const component = (
+      <Provider store={store}>
+        <TodoList />
+      </Provider>
+    );
+
+    render(component);
+    const todoElems = screen.getAllByText(/something/i);
+
+    expect(todoElems.length).toEqual(4);
+  });
+
+  test('should execute with 2 elements and end up with 1 after delete', () => {
+    const initialState = {
+      todos: [
+        { id: 1, text: 'Sing something', date: new Date() },
+        { id: 2, text: 'Dance something', date: new Date() },
+      ],
+    };
+    const store = configureStore(initialState);
+
+    const component = (
+      <Provider store={store}>
+        <TodoList />
+      </Provider>
+    );
+
+    render(component);
+    const todoElems = screen.getAllByText(/something/i);
+
+    expect(todoElems.length).toBe(2);
+
+    const buttons = screen.getAllByText('Delete');
+    expect(buttons.length).toBe(2);
+
+    fireEvent.press(buttons[0]);
+    expect(screen.getAllByText('Delete').length).toBe(1);
+  });
+});
+```
+
+## Running tests
+
+To run the tests, place a test script inside your package.json
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+And run the test script with npm test or yarn test.

package/website/docs/TestingEnvironment.md

@@ -0,0 +1,154 @@
+---
+id: testing-env
+title: Testing Environment
+---
+
+:::info
+This document is intended for more advanced audience. You should be able to write integration or component tests without reading this.
+It is intended for people who want to better understand internals of our testing environment, e.g. in order to contribute to the codebase.
+:::
+
+## Testing Environment
+
+React Native Testing Library allows you to write integration and component tests for your React Native app or library. While the JSX code used in tests closely resembles your React Native app, the things are not quite as simple as they might appear. In this document we will describe the key elements of our testing environment and highlight things to be aware of when writing more advanced tests or diagnosing issues.
+
+### React renderers
+
+React allows you to write declarative code using JSX, write function or class components, or use hooks like `useState`. In order to output the results of your components it needs to work with a renderer. Every React app uses some type of renderer: React Native is a renderer for mobile apps, web apps use React DOM, and there are other more [specialised renderers](https://github.com/chentsulin/awesome-react-renderer) that can e.g. render to console or HTML canvas.
+
+When you run your tests in React Native Testing Library, somewhat contrary to what the name suggest, they are actually **not** using React Native renderer. This is because this renderer needs to be run on iOS or Android operating system, so it would need to run on device or simulator.
+
+### React Test Renderer
+
+Instead, RNTL uses React Test Renderer which is a specialised renderer that allows rendering to pure JavaScript objects without access to mobile OS, and that can run in a Node.js environment using Jest (or any other JavaScript test runner).
+
+Using React Test Renderer has pros and cons.
+
+Benefits:
+
+- tests can run on most CIs (linux, etc) and do not require a mobile device or emulator
+- faster test execution
+- light runtime environment
+
+Disadvantages:
+
+- Tests do not execute native code
+- Tests are not aware of view state that would be managed by native components, e.g. focus, unmanaged text boxes, etc.
+- Assertions do not operate on native view hierarchy
+- Runtime behaviours are simulated, sometimes imperfectly
+
+It’s worth noting that React Testing Library (web one), works a bit different. While RTL also runs in Jest, it also has access to simulated browser DOM environment from jsdom package, so it can use a regular React DOM renderer. Unfortunately, there is no similar React Native runtime environment package. This is probably due to to the fact that while browser environment is well defined and highly standardised, the React Native environment is in constant evolution, in sync with the evolution of underlying OS-es. Maintaining such environment would require duplicating countless React Native behaviours, and keeping that in sync as React Native evolves.
+
+### Element tree
+
+Invoking `render()` function results in creation of an element tree. This is done internally by invoking `TestRenderer.create()` method. The output tree represents your React Native component tree, each node of that tree is an “instance” of some React component (to be more precise: each node represents a React fiber, and only class components have instances, while function components store the hook state using fiber).
+
+These tree elements are represented by `ReactTestInstance` type:
+
+```tsx
+interface ReactTestInstance {
+  type: ElementType;
+  props: { [propName: string]: any };
+  parent: ReactTestInstance | null;
+  children: Array<ReactTestInstance | string>;
+
+  // Other props and methods
+}
+```
+
+Based on: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-test-renderer/index.d.ts
+
+### Host and composite components
+
+One of the most important aspects of the element tree is that it is composed of both host and composite components:
+
+- [Host components](https://reactnative.dev/architecture/glossary#react-host-components-or-host-components) are components that will have direct counterparts in the native view tree. Typical examples are `<View>`, `<Text>` , `<TextInput>`, and `<Image>` from React Native. You can think of these as analogue of `<div>`, `<span>` etc on the Web. You can also create your own host views as native modules or import them from 3rd party libraries, like React Navigation or React Native Gesture Handler.
+- [Composite components](https://reactnative.dev/architecture/glossary#react-composite-components) are React code organisation units that exist only on the JavaScript side of your app. Typical examples are components you create (both function and class components), components imported from React Native (`View`, `Text`, etc) or from 3rd party packages.
+
+That might sound a bit confusing at first, since we put React Native’s `View` in both categories. There are actually two `View` components: composite one and host one. The relation between them is as follows:
+
+- composite `View` is the type imported from `react-native` package. It’s a JavaScript component, which renders host `View` as its only child in the element tree.
+- host `View` , which you do not render directly. React Native takes the props you pass to the composite `View`, does some processing on them and passes them to host `View`.
+
+The part of the tree looks as follows:
+
+```jsx
+* <View> (composite)
+  * <View> (host)
+    * children prop passed in JSX
+```
+
+Similar relation exists between other composite and host pairs: e.g. `Text` , `TextInput` and `Image` components:
+
+```jsx
+* <Text> (composite)
+  * <Text> (host)
+    * string (or mixed) content
+```
+
+Not all React Native components are organised this way, e.g. when you use `Pressable` (or `TouchableOpacity`) there is no host `Pressable`, but composite `Pressable` is rendering a host `View` with certain props being set:
+
+```jsx
+* <Pressable> (composite)
+  * <View accessible={true} {...}> (host)
+    * children prop passed in JSX
+```
+
+#### Differentiating between host and composite elements
+
+Any easy way to differentiate between host and composite elements is the `type` prop of `ReactTestInstance`:
+
+- for host components it’s always a string value representing component name, e.g. `"View"`
+- for composite components it’s a function or class corresponding to the component
+
+You can use the following code to check if given element is a host one:
+
+```jsx
+function isHostElement(element: ReactTestInstance) {
+  return typeof element.type === 'string';
+}
+```
+
+### Tree nodes
+
+We encourage you to only assert values on host views in your tests, because they represent the user interface view and controls that the user will be able to see and interact with. Users cannot see, or interact with, composite views as they exist purely in JavaScript domain and do not generate any visible UI.
+
+#### Asserting props
+
+As an example, if you make assertions on a `style` prop of a composite element, there is no guarantee that the style will be visible to the user, as the component author can forget to pass this prop to some underlying `View` or other host component. Similarly `onPress` event handler on a composite prop can be unreachable by the user.
+
+```jsx
+function ForgotToPassPropsButton({ title, onPress, style }) {
+  return (
+    <Pressable>
+      <Text>{title}</Text>
+    </Pressable>
+  );
+}
+```
+
+In the above example user defined components accepts both `onPress` and `style` props but does not pass it (through `Pressable`) to host views, so these props will not affect the user interface. Additionally, React Native and other libraries might pass some of the props under different names or transform their values between composite and host components.
+
+### Tree navigation
+
+:::caution
+You should avoid navigating over element tree, as this makes your testing code fragile and may result in false positives. This section is more relevant for people how want to contribute to our codebase.
+:::
+
+When navigating a tree of react elements using `parent` or `children` props of a `ReactTestInstance` element, you will encounter both host and composite elements. You should be careful when navigating the element tree, as the tree structure for 3rd party components and change independently from your code and cause unexpected test failures.
+
+Inside RNTL we have various tree navigation helpers: `getHostParent`, `getHostChildren`, etc. These are intentionally not exported as using them is not a recommended practice.
+
+### Queries
+
+Most of the Testing Library queries return host components, in order to encourage best practices described above.
+
+At this stage, there are some noteworthy exceptions:
+
+- `*ByText` queries returns composite `Text` element
+- `*ByDisplayValue` queries returns composite `TextInput` element
+- `*ByPlaceholderText` queries returns composite `TextInput` element
+
+This will change in the near future, as we make efforts for all queries to return host components. Meanwhile it shouldn't be a huge issue, as composite `Text` and `TextInput`generally pass their props down to host counterparts.
+
+Additionally, `UNSAFE_*ByType` and `UNSAFE_*ByProps` queries can return both host and composite components depending on used predicates. They are marked as unsafe precisely because testing composite components makes your test more fragile.