screen object#

let screen: {
  ...queries;
  rerender(element: React.Element<unknown>): void;
  unmount(): void;
  debug(options?: DebugOptions): void
  toJSON(): ReactTestRendererJSON | null;
  root: ReactTestInstance;
  UNSAFE_root: ReactTestInstance;
};

The screen object offers a recommended way to access queries and utilities for the currently rendered UI.

This object is assigned after the render call and cleared after each test by calling cleanup. If no render call has been made in a given test, then it holds a special object and throws a helpful error on each property and method access.

...queries#

The most important feature of screen is providing a set of helpful queries that allow you to find certain elements in the view hierarchy.

See Queries for a complete list.

Example#

import { render, screen } from '@testing-library/react-native';

render(<MyComponent />);
const buttonStart = screen.getByRole('button', { name: 'start' });

rerender#

Also available under update alias

function rerender(element: React.Element<unknown>): void;

Re-render the in-memory tree with a new root element. This simulates a React update render at the root. If the new element has the same type (and key) as the previous element, the tree will be updated; otherwise, it will re-mount a new tree, in both cases triggering the appropriate lifecycle events.

rerenderAsync#

Also available under updateAsync alias

function rerenderAsync(element: React.Element<unknown>): Promise<void>;

Async versions of rerender designed for working with React 19 and React Suspense. This method uses async act function internally to ensure all pending React updates are executed during updating.

import { renderAsync, screen } from '@testing-library/react-native';

test('async rerender test', async () => {
  await renderAsync(<MyComponent initialData="first" />);

  await screen.rerenderAsync(<MyComponent initialData="updated" />);
  expect(screen.getByText('updated')).toBeOnTheScreen();
});

unmount#

function unmount(): void;

Unmount the in-memory tree, triggering the appropriate lifecycle events.

unmountAsync#

function unmountAsync(): Promise<void>;

Async version of unmount designed for working with React 19 and React Suspense. This method uses async act function internally to ensure all pending React updates are executed during unmounting.

debug#

function debug(options?: { message?: string; mapProps?: MapPropsFunction }): void;

Pretty prints deeply rendered component passed to render.

message option#

You can provide a message that will be printed on top.

render(<Component />);
screen.debug({ message: 'optional message' });

logs optional message and colored JSX:

optional message

<View
  onPress={[Function bound fn]}
>
  <Text>Press me</Text>
</View>

mapProps option#

function debug({ mapProps: (props) => ({}) });

You can use the mapProps option to transform the props that will be printed :

render(<View style={{ backgroundColor: 'red' }} />);
screen.debug({ mapProps: ({ style, ...props }) => ({ props }) });

This will log the rendered JSX without the style props.

The children prop cannot be filtered out so the following will print all rendered components with all props but children filtered out.

This option can be used to target specific props when debugging a query (for instance, keeping only the children prop when debugging a getByText query).

You can also transform prop values so that they are more readable (e.g., flatten styles).

import { StyleSheet } from 'react-native';

screen.debug({ mapProps : {({ style, ...props })} => ({ style : StyleSheet.flatten(style), ...props }) });

Or remove props that have little value when debugging tests, e.g. path prop for svgs

screen.debug({ mapProps: ({ path, ...props }) => ({ ...props }) });

toJSON#

function toJSON(): ReactTestRendererJSON | null;

Get the rendered component JSON representation, e.g. for snapshot testing.

root#

const root: ReactTestInstance;

Returns the rendered root host element.

This API is primarily useful for component tests, as it allows you to access root host view without using *ByTestId queries or similar methods.

UNSAFE_root#

const UNSAFE_root: ReactTestInstance;

Returns the rendered composite root element.