screen — DOM queries

The screen API is the primary interface for finding elements on the page tested by a Run UI Test Script step. All query methods pierce shadow roots automatically, so they work with Now Experience components as well as classic Jelly and UI16 pages.

Query method variants

Each query type comes in the following variants.

Table 1. Query method variants

Variant	Returns	Throws when missing?	Async?
getBy*	Single element	Yes, throws immediately	No
getAllBy*	Array of elements	Yes, if empty	No
queryBy*	Single element or null	No	No
queryAllBy*	Array, which may be empty	No	No
findBy*	Single element	Yes, rejects the Promise	Yes, polls until found
findAllBy*	Array of elements	Yes, if empty	Yes, polls until found

Use findBy* when the element appears asynchronously, such as after an API response, animation, or navigation. Use getBy* when the element must already exist. Use queryBy* to check whether an element is absent.

Query types

Each variant supports the following query types.

Table 2. Query types

Type	Finds elements by	Example
Role	ARIA role, implicit or explicit	screen.getByRole('button', { name: 'Save' })
Text	Visible text content	screen.findByText('Incident created')
LabelText	Associated <label> text	screen.getByLabelText('Short description')
PlaceholderText	placeholder attribute	screen.getByPlaceholderText('Search…')
AltText	alt attribute	screen.getByAltText('Company logo')
Title	title attribute	screen.getByTitle('Close dialog')
TestId	data-testid attribute	screen.getByTestId('submit-btn')
DisplayValue	Current display value of a form control	screen.getByDisplayValue('High')
Selector	CSS selector, shadow-piercing	screen.getBySelector('input[name="priority"]')

getByRole is the recommended default because it validates accessibility as it queries. Use getBySelector only when no accessible query matches.

screen.waitFor(callback, options?)

Polls callback until it stops throwing. Use this method to wait for a condition that isn't directly an element query.

await screen.waitFor(() => {
  expect(screen.getByRole('status')).toHaveTextContent('Complete');
});

Options: { timeout: 5000, interval: 50 }, in milliseconds.

screen.debug(element?)

Logs the outer HTML of element, or the whole page body when omitted, to the browser console, including shadow root contents. Use it when a query doesn't match what you expect.

screen.debug(); // log the full page
screen.debug(screen.getByRole('form')); // log a specific subtree

Shadow DOM traversal

All screen.getBy*, screen.findBy*, and screen.queryBy* queries automatically pierce shadow roots. Now Experience components render their content inside shadow roots, which are normally invisible to document.querySelector. The ATF testing library traverses these boundaries transparently, so you can query by role or text whether the element is in light DOM or shadow DOM.

getByRole resolves accessible names by reading shadow root text content when the host element's own text content is empty, matching the behavior that a screen reader reports.

getBySelector uses a custom shadow-piercing CSS selector engine that handles cross-shadow combinators, for example now-typeahead input.