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"
+    }
+  }
+}