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