docs: basic cookbook docs and app

Author: mdjastrzebski

examples/cookbook/.expo-shared/assets.json

@@ -0,0 +1,4 @@
+{
+  "12bb71342c6255bbf50437ec8f4441c083f47cdb74bd89160c15e4f43e52a1cb": true,
+  "40b842e832070c58deac6aa9e08fa459302ee3f9da492c7e77d93d2fbf4a56fd": true
+}

examples/cookbook/.gitignore

@@ -0,0 +1,25 @@
+# General Node.js
+node_modules/
+.expo/
+dist/
+npm-debug.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+*.orig.*
+web-build/
+
+# Yarn 4.x
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# macOS
+.DS_Store
+

examples/cookbook/App.tsx

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { SafeAreaView } from 'react-native';
+import { LoginForm } from './components/LoginForm';
+import { Home } from './components/Home';
+
+const App = () => {
+  const [user, setUser] = React.useState<string | null>(null);
+
+  return (
+    <SafeAreaView>
+      {user == null ? <LoginForm onLoginSuccess={setUser} /> : <Home user={user} />}
+    </SafeAreaView>
+  );
+};
+
+export default App;

examples/cookbook/README.md

@@ -0,0 +1,11 @@
+# Basic RNTL setup
+
+This example is shows a basic modern React Native Testing Library setup in a template Expo app.
+
+The app and related tests written in TypeScript, and it uses recommended practices like:
+
+- testing large pieces of application instead of small components
+- using `screen`-based queries
+- using recommended query types, e.g. `*ByText`, `*ByLabelText`, `*ByPlaceholderText` over `byTestId`
+
+You also use this repository as a reference when having issues in your RNTL configuration, as it contains the recommended Jest setup.

examples/cookbook/__tests__/App.test.tsx

@@ -0,0 +1,112 @@
+import * as React from 'react';
+import { render, screen, userEvent } from '@testing-library/react-native';
+import App from '../App';
+
+jest.useFakeTimers();
+
+/**
+ * A good place to start is having a tests that your component renders correctly.
+ */
+test('renders correctly', () => {
+  // Idiom: no need to capture render output, as we will use `screen` for queries.
+  render(<App />);
+
+  // Idiom: `getBy*` queries are predicates by themselves, but we will use it with `expect().toBeOnTheScreen()`
+  // to clarify our intent.
+  expect(screen.getByRole('header', { name: 'Sign in to Example App' })).toBeOnTheScreen();
+});
+
+/**
+ * Hint: It's best when your tests are similar to what a manual test scenarions would look like,
+ * i.e. a series of actions taken by the user, followed by a series of assertions verified from
+ * his point of view.
+ */
+test('User can sign in successully with correct credentials', async () => {
+  // Setup User Event instance for realistic simulation of user interaction.
+  const user = userEvent.setup();
+
+  // Idiom: no need to capture render output, as we will use `screen` for queries.
+  render(<App />);
+
+  // Idiom: `getBy*` queries are predicates by themselves, but we will use it with `expect().toBeOnTheScreen()`
+  // to clarify our intent.
+  expect(screen.getByRole('header', { name: 'Sign in to Example App' })).toBeOnTheScreen();
+
+  // Hint: we can use `getByLabelText` to find our text inputs using their labels.
+  await user.type(screen.getByLabelText('Username'), 'admin');
+  await user.type(screen.getByLabelText('Password'), 'admin1');
+
+  // Hint: we can use `getByRole` to find our button with given text.
+  await user.press(screen.getByRole('button', { name: 'Sign In' }));
+
+  // Idiom: since pressing button triggers async operation we need to use `findBy*` query to wait
+  // for the action to complete.
+  // Hint: subsequent queries do not need to use `findBy*`, because they are used after the async action
+  // already finished
+  expect(await screen.findByRole('header', { name: 'Welcome admin!' })).toBeOnTheScreen();
+
+  // Idiom: use `queryBy*` with `expect().not.toBeOnTheScreen()` to assess that element is not present.
+  expect(screen.queryByRole('header', { name: 'Sign in to Example App' })).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Username')).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Password')).not.toBeOnTheScreen();
+});
+
+/**
+ * Another test case based on manual test scenario.
+ *
+ * Hint: Try to tests what a user would see and do, instead of assering internal component state
+ * that is not directly reflected in the UI.
+ *
+ * For this reason prefer quries that correspond to things directly observable by the user like:
+ * `getByRole`, `getByText`, `getByLabelText`, `getByPlaceholderText, `getByDisplayValue`, etc.
+ * over `getByTestId` which is not directly observable by the user.
+ *
+ * Note: that some times you will have to resort to `getByTestId`, but treat it as a last resort.
+ */
+test('User will see errors for incorrect credentials', async () => {
+  const user = userEvent.setup();
+  render(<App />);
+
+  expect(screen.getByRole('header', { name: 'Sign in to Example App' })).toBeOnTheScreen();
+
+  await user.type(screen.getByLabelText('Username'), 'admin');
+  await user.type(screen.getByLabelText('Password'), 'qwerty123');
+  await user.press(screen.getByRole('button', { name: 'Sign In' }));
+
+  // Hint: you can use custom Jest Native matcher to check text content.
+  expect(await screen.findByRole('alert')).toHaveTextContent('Incorrect username or password');
+
+  expect(screen.getByRole('header', { name: 'Sign in to Example App' })).toBeOnTheScreen();
+  expect(screen.getByLabelText('Username')).toBeOnTheScreen();
+  expect(screen.getByLabelText('Password')).toBeOnTheScreen();
+});
+
+/**
+ * Do not be afraid to write longer test scenarios, with repeating act and assert statements.
+ */
+test('User can sign in after incorrect attempt', async () => {
+  const user = userEvent.setup();
+  render(<App />);
+
+  expect(screen.getByRole('header', { name: 'Sign in to Example App' })).toBeOnTheScreen();
+
+  const usernameInput = screen.getByLabelText('Username');
+  const passwordInput = screen.getByLabelText('Password');
+
+  await user.type(usernameInput, 'admin');
+  await user.type(passwordInput, 'qwerty123');
+  await user.press(screen.getByRole('button', { name: 'Sign In' }));
+
+  expect(await screen.findByRole('alert')).toHaveTextContent('Incorrect username or password');
+
+  // Clear password field
+  await user.clear(passwordInput);
+
+  await user.type(passwordInput, 'admin1');
+  await user.press(screen.getByRole('button', { name: 'Sign In' }));
+
+  expect(await screen.findByText('Welcome admin!')).toBeOnTheScreen();
+  expect(screen.queryByRole('header', { name: 'Sign in to Example App' })).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Username')).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Password')).not.toBeOnTheScreen();
+});

examples/cookbook/app.json

@@ -0,0 +1,31 @@
+{
+  "expo": {
+    "name": "RNTL Example Basic",
+    "slug": "rntl-example-basic",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "splash": {
+      "image": "./assets/splash.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#ffffff"
+    },
+    "updates": {
+      "fallbackToCacheTimeout": 0
+    },
+    "assetBundlePatterns": ["**/*"],
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/adaptive-icon.png",
+        "backgroundColor": "#FFFFFF"
+      }
+    },
+    "web": {
+      "favicon": "./assets/favicon.png"
+    }
+  }
+}

examples/cookbook/assets/adaptive-icon.png

@@ -0,0 +1,6 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+  };
+};

examples/cookbook/assets/favicon.png

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { StyleSheet, View, Text } from 'react-native';
+
+type Props = {
+  user: string;
+};
+
+export function Home({ user }: Props) {
+  return (
+    <View style={styles.container}>
+      <Text accessibilityRole="header" style={styles.title}>
+        Welcome {user}!
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 20,
+  },
+  title: {
+    alignSelf: 'center',
+    fontSize: 24,
+    marginTop: 8,
+    marginBottom: 40,
+  },
+});

examples/cookbook/assets/icon.png

@@ -0,0 +1,128 @@
+import * as React from 'react';
+import { StyleSheet, View, Text, TextInput, Pressable, ActivityIndicator } from 'react-native';
+
+type Props = {
+  onLoginSuccess: (user: string) => void;
+};
+
+export function LoginForm({ onLoginSuccess }: Props) {
+  const [username, setUsername] = React.useState('');
+  const [password, setPassword] = React.useState('');
+  const [error, setError] = React.useState<string | undefined>();
+  const [isLoading, setIsLoading] = React.useState(false);
+
+  const handleSignIn = async () => {
+    setIsLoading(true);
+
+    const user = await authUser(username, password);
+    setIsLoading(false);
+
+    if (user) {
+      setError(undefined);
+      onLoginSuccess(user);
+    } else {
+      setError('Incorrect username or password');
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text accessibilityRole="header" style={styles.title}>
+        Sign in to Example App
+      </Text>
+
+      <Text style={styles.textLabel}>Username</Text>
+      <TextInput
+        value={username}
+        onChangeText={setUsername}
+        accessibilityLabel="Username"
+        autoCapitalize="none"
+        style={styles.textInput}
+      />
+
+      <Text style={styles.textLabel}>Password</Text>
+      <TextInput
+        value={password}
+        onChangeText={setPassword}
+        accessibilityLabel="Password"
+        secureTextEntry={true}
+        style={styles.textInput}
+      />
+
+      {error && (
+        <Text accessibilityRole="alert" style={styles.validator}>
+          {error}
+        </Text>
+      )}
+
+      <Pressable
+        accessibilityRole="button"
+        disabled={isLoading}
+        onPress={handleSignIn}
+        style={styles.button}
+      >
+        {isLoading ? (
+          <ActivityIndicator color="white" />
+        ) : (
+          <Text style={styles.buttonText}>Sign In</Text>
+        )}
+      </Pressable>
+    </View>
+  );
+}
+
+/**
+ * Fake authentication function according to our abilities.
+ * @param username The username to authenticate.
+ * @param password The password to authenticate.
+ * @returns username if the username and password are correct, null otherwise.
+ */
+async function authUser(username: string, password: string): Promise<string | null> {
+  return new Promise((resolve) =>
+    setTimeout(() => {
+      const hasValidCredentials = username === 'admin' && password === 'admin1';
+      resolve(hasValidCredentials ? username : null);
+    }, 250),
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 20,
+  },
+  title: {
+    alignSelf: 'center',
+    fontSize: 24,
+    marginTop: 8,
+    marginBottom: 40,
+  },
+  textLabel: {
+    fontSize: 16,
+    color: '#444',
+  },
+  textInput: {
+    fontSize: 20,
+    padding: 8,
+    marginVertical: 8,
+    borderColor: 'black',
+    borderWidth: 1,
+  },
+  button: {
+    backgroundColor: '#3256a8',
+    padding: 16,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginTop: 20,
+    minHeight: 56,
+  },
+  buttonText: {
+    fontSize: 20,
+    fontWeight: '600',
+    color: 'white',
+  },
+  validator: {
+    color: 'red',
+    fontSize: 18,
+    marginTop: 8,
+  },
+});

examples/cookbook/assets/splash.png

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { renderWithProviders } from './test-utils';
+import { WelcomeScreen } from './WelcomeScreen';
+
+test('renders WelcomeScreen in light theme', () => {
+  renderWithProviders(<WelcomeScreen />, { theme: 'light' });
+});

examples/cookbook/babel.config.js

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { useUser } from './providers/user-provider';
+import { useTheme } from './providers/theme-provider';
+
+export function WelcomeScreen() {
+  const theme = useTheme();
+  const user = useUser();
+
+  return (
+    <View>
+      <Text>{user ? `User: ${user.name}` : 'Not logged in.'}</Text>
+      <Text>Theme: {theme}</Text>
+    </View>
+  );
+}