chore: update examples to use toBeOnTheScreen() (#1267)

Author: mdjastrzebski

examples/basic/__tests__/App.test.tsx

@@ -9,11 +9,11 @@ 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().toBeTruthy()`
+  // 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' })
-  ).toBeTruthy();
+  ).toBeOnTheScreen();
 });
 
 /**
@@ -25,12 +25,11 @@ test('User can sign in successully with correct credentials', async () => {
   // 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().toBeTruthy()`
+  // Idiom: `getBy*` queries are predicates by themselves, but we will use it with `expect().toBeOnTheScreen()`
   // to clarify our intent.
-  // Note: `.toBeTruthy()` is the preferred matcher for checking that elements are present.
   expect(
     screen.getByRole('header', { name: 'Sign in to Example App' })
-  ).toBeTruthy();
+  ).toBeOnTheScreen();
 
   // Hint: we can use `getByLabelText` to find our text inputs using their labels.
   fireEvent.changeText(screen.getByLabelText('Username'), 'admin');
@@ -45,14 +44,14 @@ test('User can sign in successully with correct credentials', async () => {
   // already finished
   expect(
     await screen.findByRole('header', { name: 'Welcome admin!' })
-  ).toBeTruthy();
+  ).toBeOnTheScreen();
 
-  // Idiom: use `queryBy*` with `expect().toBeFalsy()` to assess that element is not present.
+  // Idiom: use `queryBy*` with `expect().not.toBeOnTheScreen()` to assess that element is not present.
   expect(
     screen.queryByRole('header', { name: 'Sign in to Example App' })
-  ).toBeFalsy();
-  expect(screen.queryByLabelText('Username')).toBeFalsy();
-  expect(screen.queryByLabelText('Password')).toBeFalsy();
+  ).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Username')).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Password')).not.toBeOnTheScreen();
 });
 
 /**
@@ -72,7 +71,7 @@ test('User will see errors for incorrect credentials', async () => {
 
   expect(
     screen.getByRole('header', { name: 'Sign in to Example App' })
-  ).toBeTruthy();
+  ).toBeOnTheScreen();
 
   fireEvent.changeText(screen.getByLabelText('Username'), 'admin');
   fireEvent.changeText(screen.getByLabelText('Password'), 'qwerty123');
@@ -85,9 +84,9 @@ test('User will see errors for incorrect credentials', async () => {
 
   expect(
     screen.getByRole('header', { name: 'Sign in to Example App' })
-  ).toBeTruthy();
-  expect(screen.getByLabelText('Username')).toBeTruthy();
-  expect(screen.getByLabelText('Password')).toBeTruthy();
+  ).toBeOnTheScreen();
+  expect(screen.getByLabelText('Username')).toBeOnTheScreen();
+  expect(screen.getByLabelText('Password')).toBeOnTheScreen();
 });
 
 /**
@@ -98,7 +97,7 @@ test('User can sign in after incorrect attempt', async () => {
 
   expect(
     screen.getByRole('header', { name: 'Sign in to Example App' })
-  ).toBeTruthy();
+  ).toBeOnTheScreen();
 
   fireEvent.changeText(screen.getByLabelText('Username'), 'admin');
   fireEvent.changeText(screen.getByLabelText('Password'), 'qwerty123');
@@ -111,10 +110,10 @@ test('User can sign in after incorrect attempt', async () => {
   fireEvent.changeText(screen.getByLabelText('Password'), 'admin1');
   fireEvent.press(screen.getByRole('button', { name: 'Sign In' }));
 
-  expect(await screen.findByText('Welcome admin!')).toBeTruthy();
+  expect(await screen.findByText('Welcome admin!')).toBeOnTheScreen();
   expect(
     screen.queryByRole('header', { name: 'Sign in to Example App' })
-  ).toBeFalsy();
-  expect(screen.queryByLabelText('Username')).toBeFalsy();
-  expect(screen.queryByLabelText('Password')).toBeFalsy();
+  ).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Username')).not.toBeOnTheScreen();
+  expect(screen.queryByLabelText('Password')).not.toBeOnTheScreen();
 });

examples/basic/jest-setup.js

@@ -1,7 +1,13 @@
 /* eslint-disable no-undef, import/no-extraneous-dependencies */
+import { configure } from '@testing-library/react-native';
 
 // 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');
+
+// Enable excluding hidden elements from the queries by default
+configure({
+  defaultIncludeHiddenElements: false,
+});

examples/basic/package.json

@@ -19,7 +19,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.19.3",
-    "@testing-library/jest-native": "^5.1.2",
+    "@testing-library/jest-native": "^5.4.0",
     "@testing-library/react-native": "^11.4.0",
     "@types/react": "~18.0.24",
     "@types/react-native": "~0.70.6",

examples/react-navigation/jest-setup.js

@@ -1,4 +1,4 @@
-/* eslint-disable import/no-extraneous-dependencies */
+/* eslint-disable no-undef, import/no-extraneous-dependencies */
 import { configure } from '@testing-library/react-native';
 
 // Import Jest Native matchers

examples/react-navigation/package.json

@@ -21,7 +21,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.20.2",
-    "@testing-library/jest-native": "^5.3.0",
+    "@testing-library/jest-native": "^5.4.0",
     "@testing-library/react-native": "^11.5.0",
     "babel-jest": "^29.3.1",
     "jest": "^29.3.0",

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

@@ -7,7 +7,7 @@ test('Changing screens', () => {
   renderNavigator(<DrawerNavigator />);
 
   // Assert initial screen
-  expect(screen.getByRole('header', { name: 'Home screen' })).toBeTruthy();
+  expect(screen.getByRole('header', { name: 'Home screen' })).toBeOnTheScreen();
 
   // Open drawer by pressing button
   const toggleButton = screen.getByText('Toggle drawer');
@@ -33,6 +33,10 @@ test('Changing screens', () => {
   ).toHaveAccessibilityState({ selected: true });
 
   // Assert visible screen
-  expect(screen.getByRole('header', { name: 'Settings screen' })).toBeTruthy();
-  expect(screen.queryByRole('header', { name: 'Home screen' })).toBeFalsy();
+  expect(
+    screen.getByRole('header', { name: 'Settings screen' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
 });

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

@@ -6,12 +6,12 @@ import NativeStackNavigator from './NativeStackNavigator';
 test('Home screen contains the header and list of items', () => {
   renderNavigator(<NativeStackNavigator />);
 
-  expect(screen.getByRole('header', { name: 'Home screen' })).toBeTruthy();
+  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 })
-  ).toBeFalsy();
+  ).not.toBeOnTheScreen();
 });
 
 test('Pressing an item takes user to the details screen', () => {
@@ -22,9 +22,13 @@ test('Pressing an item takes user to the details screen', () => {
 
   expect(
     screen.getByRole('header', { name: 'Details for Item 5' })
-  ).toBeTruthy();
-  expect(screen.getByText('The number you have chosen is 5.')).toBeTruthy();
+  ).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' })).toBeFalsy();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
 });

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

@@ -6,12 +6,12 @@ import StackNavigator from './StackNavigator';
 test('Home screen contains the header and list of items', () => {
   renderNavigator(<StackNavigator />);
 
-  expect(screen.getByRole('header', { name: 'Home screen' })).toBeTruthy();
+  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 })
-  ).toBeFalsy();
+  ).not.toBeOnTheScreen();
 });
 
 test('Pressing an item takes user to the details screen', () => {
@@ -22,9 +22,13 @@ test('Pressing an item takes user to the details screen', () => {
 
   expect(
     screen.getByRole('header', { name: 'Details for Item 5' })
-  ).toBeTruthy();
-  expect(screen.getByText('The number you have chosen is 5.')).toBeTruthy();
+  ).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' })).toBeFalsy();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
 });

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

@@ -5,13 +5,17 @@ import TabNavigator from './TabNavigator';
 
 test('Changing tabs', () => {
   renderNavigator(<TabNavigator />);
-  expect(screen.getByRole('header', { name: 'Home screen' })).toBeTruthy();
+  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' })).toBeTruthy();
-  expect(screen.queryByRole('header', { name: 'Home screen' })).toBeFalsy();
+  expect(
+    screen.getByRole('header', { name: 'Settings screen' })
+  ).toBeOnTheScreen();
+  expect(
+    screen.queryByRole('header', { name: 'Home screen' })
+  ).not.toBeOnTheScreen();
 });

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

@@ -16,8 +16,10 @@ test('Details screen contains the header and content', () => {
 
   expect(
     screen.getByRole('header', { name: 'Details for Item 100' })
-  ).toBeTruthy();
-  expect(screen.getByText('The number you have chosen is 100.')).toBeTruthy();
+  ).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' }));

package.json

@@ -35,7 +35,7 @@
     "@babel/preset-react": "^7.18.6",
     "@babel/preset-typescript": "^7.18.6",
     "@callstack/eslint-config": "^13.0.1",
-    "@testing-library/jest-native": "^5.0.0",
+    "@testing-library/jest-native": "^5.4.0",
     "@types/jest": "^29.2.3",
     "@types/react": "~18.0.18",
     "@types/react-native": "~0.70.0",

website/docs/API.md

@@ -672,10 +672,10 @@ Please note that additional `render` specific operations like `update`, `unmount
 
 ```jsx
 const detailsScreen = within(screen.getByA11yHint('Details Screen'));
-expect(detailsScreen.getByText('Some Text')).toBeTruthy();
-expect(detailsScreen.getByDisplayValue('Some Value')).toBeTruthy();
-expect(detailsScreen.queryByLabelText('Some Label')).toBeTruthy();
-await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeTruthy();
+expect(detailsScreen.getByText('Some Text')).toBeOnTheScreen();
+expect(detailsScreen.getByDisplayValue('Some Value')).toBeOnTheScreen();
+expect(detailsScreen.queryByLabelText('Some Label')).toBeOnTheScreen();
+await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeOnTheScreen();
 ```
 
 Use cases for scoped queries include:
@@ -692,7 +692,7 @@ import { render, screen } from '@testing-library/react-native';
 
 render(<Form />);
 const submitButton = screen.queryByText('submit');
-expect(submitButton).toBeNull(); // it doesn't exist
+expect(submitButton).not.toBeOnTheScreen(); // it doesn't exist
 ```
 
 ## `queryAll` APIs

website/docs/Queries.md

@@ -426,13 +426,13 @@ render(<Text style={{ display: 'none' }}>Hidden from accessibility</Text>);
 // Exclude hidden elements
 expect(
   screen.queryByText('Hidden from accessibility', { includeHiddenElements: false })
-).toBeFalsy();
+).not.toBeOnTheScreen();
 
 // Include hidden elements
-expect(screen.getByText('Hidden from accessibility')).toBeTruthy();
+expect(screen.getByText('Hidden from accessibility')).toBeOnTheScreen();
 expect(
   screen.getByText('Hidden from accessibility', { includeHiddenElements: true })
-).toBeTruthy();
+).toBeOnTheScreen();
 ```
 
 ## TextMatch

website/docs/ReactNavigation.md

@@ -182,7 +182,7 @@ describe('Testing react navigation', () => {
     const header = await screen.findByText('List of numbers from 1 to 20');
     const items = await screen.findAllByText(/Item number/);
 
-    expect(header).toBeTruthy();
+    expect(header).toBeOnTheScreen();
     expect(items.length).toBe(10);
   });
 
@@ -200,8 +200,8 @@ describe('Testing react navigation', () => {
     const newHeader = await screen.findByText('Showing details for 5');
     const newBody = await screen.findByText('the number you have chosen is 5');
 
-    expect(newHeader).toBeTruthy();
-    expect(newBody).toBeTruthy();
+    expect(newHeader).toBeOnTheScreen();
+    expect(newBody).toBeOnTheScreen();
   });
 });
 ```
@@ -329,7 +329,7 @@ describe('Testing react navigation', () => {
     render(component);
     const button = await screen.findByText('Go to notifications');
 
-    expect(button).toBeTruthy();
+    expect(button).toBeOnTheScreen();
   });
 
   test('clicking on the button takes you to the notifications screen', async () => {
@@ -343,12 +343,12 @@ describe('Testing react navigation', () => {
     const oldScreen = screen.queryByText('Welcome!');
     const button = await screen.findByText('Go to notifications');
 
-    expect(oldScreen).toBeTruthy();
+    expect(oldScreen).toBeOnTheScreen();
 
     fireEvent(button, 'press');
     const newScreen = await screen.findByText('This is the notifications screen');
 
-    expect(newScreen).toBeTruthy();
+    expect(newScreen).toBeOnTheScreen();
   });
 });
 ```

website/docs/ReduxIntegration.md

@@ -37,7 +37,7 @@ describe('AddTodo component test', () => {
     // 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).toBeTruthy();
+    expect(input).toBeOnTheScreen();
 
     const textToEnter = 'This is a random element';
     fireEvent.changeText(input, textToEnter);