#screen object

let screen: {
  ...queries;
  rerender(element: React.Element<unknown>): Promise<void>;
  unmount(): Promise<void>;
  debug(options?: DebugOptions): void
  toJSON(): JsonElement | null;
  container: HostElement;
  root: HostElement | null;
};

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';

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

#rerender

function rerender(element: React.Element<unknown>): Promise<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.

This method is async and uses async act function internally to ensure all pending React updates are executed during updating, making it compatible with async React features like Suspense boundary or use() hook.

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

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

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

#unmount

function unmount(): Promise<void>;

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

This method is async and uses async act function internally to ensure all pending React updates are executed during unmounting, making it compatible with async React features like Suspense boundary or use() hook.

#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.

await 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 :

await 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(): JsonElement | null;

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

#container

const container: HostElement;

Returns a pseudo-element container whose children are the elements you asked to render. This is the root container element from Test Renderer.

The container is safe to use and provides access to the entire rendered tree. It's useful when you need to query or manipulate the entire rendered output, similar to how container works in React Testing Library.

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

test('example', async () => {
  await render(<MyComponent />);
  // container contains the entire rendered tree
  const container = screen.container;
  expect(container).toBeTruthy();
});

#root

const root: HostElement | null;

Returns the rendered root host element, or null if nothing was rendered. This is the first child of the container, which represents the actual root element you rendered.

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

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

test('example', async () => {
  await render(
    <View testID="root-view">
      <Text>Hello</Text>
    </View>
  );
  // root is the View element you rendered
  expect(screen.root.props.testID).toBe('root-view');
});