@testing-library/react-native 12.1.2 → 12.2.0

package/examples/react-navigation/README.md

@@ -0,0 +1,16 @@
+# RNTL example app for React Navigation
+
+**Note: this example is stale and might not function correctly.**
+
+This example shows how to write integration tests using React Navigation without mocking it. Presented approach has been consulted with and influenced by React Navigation team.
+
+## Recommended tests
+
+There are two types of recommeded tests:
+1. Tests operating on navigator level - these use `renderNavigator` helper to render a navigator component used in the app. It is useful when you want to test a scenario that includes multiple screens.
+2. Tests operating on single screen level - these use regular `render` helper but require refactoring screen components into `Screen` and `ScreenContent` components. Where `Screen` receives React Navigation props and/or uses hooks like `useNavigation` while `ScreenContent` does not have a direct relation to React Navigation API but gets props from `Screen` and calls relevant callbacks to trigger navigation.
+
+## Non-recommended tests
+
+There also exists another popular type of screen level tests, where users mock React Navigation objects like `navigation`, `route` and/or hooks like  `useNavigation`, etc. We don't recommend this way of testing. **Mocking internal parts of the libraries is effectively testing implementation details, which goes against the Testing Library's [Guiding Principles](https://testing-library.com/docs/guiding-principles/)**.
+

package/examples/react-navigation/babel.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  presets: ['module:metro-react-native-babel-preset'],
+  plugins: ['react-native-reanimated/plugin'],
+};

package/examples/react-navigation/jest-setup.js

@@ -0,0 +1,11 @@
+/* eslint-disable no-undef, import/no-extraneous-dependencies */
+
+// Import Jest Native matchers
+import '@testing-library/jest-native/extend-expect';
+
+// Silence the warning: Animated: `useNativeDriver` is not supported because the native animated module is missing
+jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper');
+
+// Setup Reanimated mocking for Drawer navigation
+global.ReanimatedDataMock = { now: () => Date.now() };
+require('react-native-reanimated/lib/reanimated2/jestUtils').setUpTests();

package/examples/react-navigation/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  preset: 'react-native',
+  setupFilesAfterEnv: [
+    './node_modules/react-native-gesture-handler/jestSetup.js',
+    './jest-setup.js',
+  ],
+  transformIgnorePatterns: [
+    'node_modules/(?!(jest-)?react-native|@react-native|@react-native-community|@react-navigation)',
+  ],
+};

package/examples/react-navigation/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "react-navigation-example",
+  "description": "Testing React Navigation with RNTL",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {
+    "@react-navigation/bottom-tabs": "^6.4.1",
+    "@react-navigation/drawer": "^6.5.1",
+    "@react-navigation/native": "^6.0.14",
+    "@react-navigation/native-stack": "^6.9.2",
+    "@react-navigation/stack": "^6.3.5",
+    "react": "18.2.0",
+    "react-native": "0.72.3",
+    "react-native-gesture-handler": "^2.8.0",
+    "react-native-reanimated": "^2.13.0",
+    "react-native-safe-area-context": "^4.4.1",
+    "react-native-screens": "^3.18.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.20.2",
+    "@testing-library/jest-native": "^5.4.2",
+    "@testing-library/react-native": "^12.1.3",
+    "babel-jest": "^29.3.1",
+    "jest": "^29.3.0",
+    "metro-react-native-babel-preset": "^0.72.3",
+    "react-test-renderer": "18.2.0"
+  }
+}

package/examples/react-navigation/src/App.js

@@ -0,0 +1,21 @@
+import React from 'react';
+import { StatusBar, StyleSheet, View } from 'react-native';
+import { NavigationContainer } from '@react-navigation/native';
+import AppNavigator from './NativeStackNavigator';
+
+export default function App() {
+  return (
+    <NavigationContainer>
+      <View style={styles.container}>
+        <StatusBar barStyle="dark-content" />
+        <AppNavigator />
+      </View>
+    </NavigationContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});

package/examples/react-navigation/src/DrawerNavigator.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { createDrawerNavigator } from '@react-navigation/drawer';
+import DrawerHomeScreen from './screens/DrawerHomeScreen';
+import SettingsScreen from './screens/SettingsScreen';
+
+const Drawer = createDrawerNavigator();
+
+export default function Navigation() {
+  return (
+    <Drawer.Navigator>
+      <Drawer.Screen name="Home" component={DrawerHomeScreen} />
+      <Drawer.Screen name="Settings" component={SettingsScreen} />
+    </Drawer.Navigator>
+  );
+}

package/examples/react-navigation/src/DrawerNavigator.test.js

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { screen, fireEvent } from '@testing-library/react-native';
+import { renderNavigator } from './test-utils';
+import DrawerNavigator from './DrawerNavigator';
+
+test('Changing screens', () => {
+  renderNavigator(<DrawerNavigator />);
+
+  // Assert initial screen
+  expect(screen.getByRole('header', { name: 'Home screen' })).toBeOnTheScreen();
+
+  // Open drawer by pressing button
+  const toggleButton = screen.getByText('Toggle drawer');
+  fireEvent.press(toggleButton);
+
+  // Assert drawer state
+  expect(screen.getByRole('button', { name: 'Home' })).toHaveAccessibilityState(
+    { selected: true }
+  );
+  expect(
+    screen.getByRole('button', { name: 'Settings' })
+  ).toHaveAccessibilityState({ selected: false });
+
+  // Press drawer item
+  fireEvent.press(screen.getByRole('button', { name: 'Settings' }));
+
+  // Assert drawer state after action
+  expect(screen.getByRole('button', { name: 'Home' })).toHaveAccessibilityState(
+    { selected: false }
+  );
+  expect(
+    screen.getByRole('button', { name: 'Settings' })
+  ).toHaveAccessibilityState({ selected: true });
+
+  // Assert visible screen
+  expect(
+    screen.getByRole('header', { name: 'Settings screen' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
+});

package/examples/react-navigation/src/NativeStackNavigator.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import HomeScreen from './screens/HomeScreen';
+import DetailsScreen from './screens/DetailsScreen';
+
+const Stack = createNativeStackNavigator();
+
+export default function Navigation() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Home" component={HomeScreen} />
+      <Stack.Screen name="Details" component={DetailsScreen} />
+    </Stack.Navigator>
+  );
+}

package/examples/react-navigation/src/NativeStackNavigator.test.js

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { screen, fireEvent } from '@testing-library/react-native';
+import { renderNavigator } from './test-utils';
+import NativeStackNavigator from './NativeStackNavigator';
+
+test('Home screen contains the header and list of items', () => {
+  renderNavigator(<NativeStackNavigator />);
+
+  expect(screen.getByRole('header', { name: 'Home screen' })).toBeOnTheScreen();
+  expect(screen.getAllByRole('button', { name: /Item/ })).toHaveLength(10);
+
+  expect(
+    screen.queryByRole('header', { name: /Details for item/i })
+  ).not.toBeOnTheScreen();
+});
+
+test('Pressing an item takes user to the details screen', () => {
+  renderNavigator(<NativeStackNavigator />);
+
+  const item5 = screen.getByRole('button', { name: 'Item 5' });
+  fireEvent.press(item5);
+
+  expect(
+    screen.getByRole('header', { name: 'Details for Item 5' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.getByText('The number you have chosen is 5.')
+  ).toBeOnTheScreen();
+
+  // Home screen is still in the element tree but it is hidden from accessibility
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
+});

package/examples/react-navigation/src/StackNavigator.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { createStackNavigator } from '@react-navigation/stack';
+import HomeScreen from './screens/HomeScreen';
+import DetailsScreen from './screens/DetailsScreen';
+
+const Stack = createStackNavigator();
+
+export default function Navigation() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Home" component={HomeScreen} />
+      <Stack.Screen name="Details" component={DetailsScreen} />
+    </Stack.Navigator>
+  );
+}

package/examples/react-navigation/src/StackNavigator.test.js

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { screen, fireEvent } from '@testing-library/react-native';
+import { renderNavigator } from './test-utils';
+import StackNavigator from './StackNavigator';
+
+test('Home screen contains the header and list of items', () => {
+  renderNavigator(<StackNavigator />);
+
+  expect(screen.getByRole('header', { name: 'Home screen' })).toBeOnTheScreen();
+  expect(screen.getAllByRole('button', { name: /Item/ })).toHaveLength(10);
+
+  expect(
+    screen.queryByRole('header', { name: /Details for item/i })
+  ).not.toBeOnTheScreen();
+});
+
+test('Pressing an item takes user to the details screen', () => {
+  renderNavigator(<StackNavigator />);
+
+  const item5 = screen.getByRole('button', { name: 'Item 5' });
+  fireEvent.press(item5);
+
+  expect(
+    screen.getByRole('header', { name: 'Details for Item 5' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.getByText('The number you have chosen is 5.')
+  ).toBeOnTheScreen();
+
+  // Home screen is still in the element tree but it is hidden from accessibility
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
+});

package/examples/react-navigation/src/TabNavigator.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+import HomeScreen from './screens/HomeScreen';
+import SettingsScreen from './screens/SettingsScreen';
+
+const Tab = createBottomTabNavigator();
+
+export default function Navigation() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name="Home" component={HomeScreen} />
+      <Tab.Screen name="Settings" component={SettingsScreen} />
+    </Tab.Navigator>
+  );
+}

package/examples/react-navigation/src/TabNavigator.test.js

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { screen, fireEvent } from '@testing-library/react-native';
+import { renderNavigator } from './test-utils';
+import TabNavigator from './TabNavigator';
+
+test('Changing tabs', () => {
+  renderNavigator(<TabNavigator />);
+  expect(screen.getByRole('header', { name: 'Home screen' })).toBeOnTheScreen();
+
+  // Note: React Navigation uses `button` role for tab buttons as workaround.
+  // It should actually be `tab` role.
+  const settingsTab = screen.getByRole('button', { name: 'Settings' });
+  fireEvent.press(settingsTab);
+
+  expect(
+    screen.getByRole('header', { name: 'Settings screen' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
+});

package/examples/react-navigation/src/screens/DetailsScreen.js

@@ -0,0 +1,43 @@
+import * as React from 'react';
+import { StyleSheet, View, Text, Pressable } from 'react-native';
+
+export default function DetailsScreen({ navigation, route }) {
+  const item = route.params;
+  return (
+    <DetailsScreenContent item={item} onGoBack={() => navigation.goBack()} />
+  );
+}
+
+export function DetailsScreenContent({ item, onGoBack }) {
+  return (
+    <View>
+      <Text accessibilityRole="header" style={styles.header}>
+        Details for {item.title}
+      </Text>
+      <Text style={styles.body}>
+        The number you have chosen is {item.value}.
+      </Text>
+
+      <BackButton onPress={onGoBack} />
+    </View>
+  );
+}
+
+function BackButton({ onPress }) {
+  return (
+    <Pressable accessibilityRole="button" onPress={onPress}>
+      <Text>Go Back</Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+  body: {
+    textAlign: 'center',
+  },
+});

package/examples/react-navigation/src/screens/DetailsScreen.test.js

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react-native';
+import { DetailsScreenContent } from './DetailsScreen';
+
+test('Details screen contains the header and content', () => {
+  const item = {
+    id: 100,
+    title: 'Item 100',
+    value: 100,
+  };
+
+  const onGoBack = jest.fn();
+
+  // Passing both navigation and route to the screen as props
+  render(<DetailsScreenContent item={item} onGoBack={onGoBack} />);
+
+  expect(
+    screen.getByRole('header', { name: 'Details for Item 100' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.getByText('The number you have chosen is 100.')
+  ).toBeOnTheScreen();
+
+  // Note: Go Back button get navigation from `useNavigation` hook
+  fireEvent.press(screen.getByRole('button', { name: 'Go Back' }));
+  expect(onGoBack).toHaveBeenCalledTimes(1);
+});

package/examples/react-navigation/src/screens/DrawerHomeScreen.js

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { StyleSheet, View, Text, Pressable } from 'react-native';
+
+export default function DrawerHomeScreen({ navigation }) {
+  const handleToggleDrawer = () => navigation.toggleDrawer();
+
+  return (
+    <View>
+      <Text accessibilityRole="header" style={styles.header}>
+        Home screen
+      </Text>
+
+      <Pressable accessiblityRole="button" onPress={handleToggleDrawer}>
+        <Text>Toggle drawer</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+});

package/examples/react-navigation/src/screens/HomeScreen.js

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { StyleSheet, View, Text, FlatList, Pressable } from 'react-native';
+
+const mockData = new Array(20).fill(null).map((_, index) => ({
+  id: index + 1,
+  title: `Item ${index + 1}`,
+  value: index + 1,
+}));
+
+export default function HomeScreen({ navigation }) {
+  const handleItemPress = (item) => navigation.navigate('Details', item);
+
+  const renderItem = ({ item }) => {
+    return (
+      <Pressable
+        accessibilityRole="button"
+        onPress={() => handleItemPress(item)}
+        style={styles.row}
+      >
+        <Text>{item.title}</Text>
+      </Pressable>
+    );
+  };
+
+  return (
+    <View>
+      <Text accessibilityRole="header" style={styles.header}>
+        Home screen
+      </Text>
+
+      <FlatList data={mockData} renderItem={renderItem} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+  row: {
+    paddingVertical: 16,
+    paddingHorizontal: 24,
+    borderBottomColor: '#DDDDDD',
+    borderBottomWidth: 1,
+  },
+});

package/examples/react-navigation/src/screens/SettingsScreen.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { StyleSheet, View, Text } from 'react-native';
+
+export default function SettingsScreen() {
+  return (
+    <View>
+      <Text accessibilityRole="header" style={styles.header}>
+        Settings screen
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: {
+    fontSize: 20,
+    textAlign: 'center',
+    marginVertical: 16,
+  },
+});

package/examples/react-navigation/src/test-utils.js

@@ -0,0 +1,12 @@
+/* eslint-disable no-undef, import/no-extraneous-dependencies */
+import * as React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { render } from '@testing-library/react-native';
+
+/**
+ * Render given JSX inside Navigation container.
+ * This should be used for rendering whole navigators as used by real app.
+ */
+export function renderNavigator(ui) {
+  return render(<NavigationContainer>{ui}</NavigationContainer>);
+}