screen — DOM queries

  • Release version: Australia
  • Updated June 25, 2026
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of screen — DOM queries

    The Screen API is the main tool used in ServiceNow Automated Test Framework (ATF) to locate elements on a web page during UI test scripts. It automatically traverses shadow DOM boundaries, enabling queries on both Now Experience components and classic UI pages seamlessly.

    Show full answer Show less

    Query Method Variants

    The API provides multiple query method variants, each serving different purposes:

    • getBy: Returns a single element; throws an error immediately if not found; synchronous.
    • getAllBy: Returns an array of elements; throws if none found; synchronous.
    • queryBy: Returns a single element or null; does not throw; synchronous.
    • queryAllBy: Returns an array which may be empty; does not throw; synchronous.
    • findBy: Returns a single element; returns a rejected Promise if not found; asynchronous with polling until found.
    • findAllBy: Returns an array of elements; rejects Promise if empty; asynchronous with polling.

    Use findBy when elements appear asynchronously (e.g., after navigation or API responses), getBy when the element must already exist, and queryBy to verify element absence.

    Query Types

    The Screen API supports querying elements by various criteria, allowing flexible and accessible selectors:

    • Role: ARIA roles (recommended default for accessibility validation). Example: screen.getByRole('button', { name: 'Save' })
    • Text: Visible text content. Example: screen.findByText('Incident created')
    • LabelText: Text associated with a <label>. Example: screen.getByLabelText('Short description')
    • PlaceholderText: Placeholder attribute. Example: screen.getByPlaceholderText('Search…')
    • AltText: Alt attribute of images. Example: screen.getByAltText('Company logo')
    • Title: Title attribute. Example: screen.getByTitle('Close dialog')
    • TestId: data-testid attribute. Example: screen.getByTestId('submit-btn')
    • DisplayValue: Current value of form controls. Example: screen.getByDisplayValue('High')
    • Selector: CSS selector with shadow DOM piercing. Example: screen.getBySelector('input[name="priority"]')

    Use getByRole as the default for accessibility-compliant queries. Resort to getBySelector only when no accessible queries apply.

    Additional Utilities

    • screen.waitFor(callback, options): Polls a callback function until it stops throwing errors, useful to wait for conditions beyond element queries. Options let you specify timeout and polling interval in milliseconds.
    • screen.debug(element?): Logs the outer HTML of the specified element or the entire page body (including shadow DOM content) to the browser console. Helpful for troubleshooting query mismatches.

    Shadow DOM Traversal

    All getBy, findBy, and queryBy queries automatically pierce Shadow DOM boundaries, allowing tests to interact with Now Experience components rendered inside shadow roots. This ensures consistent access whether elements are in light DOM or shadow DOM.

    The getByRole method resolves accessible names by reading shadow root text content when the host element’s text is empty, accurately reflecting what screen readers detect. The getBySelector method uses a specialized CSS selector engine that supports cross-shadow combinators.

    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.