--- sourceDocument: Australia API Reference sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/api-reference Release : - australia ft:locale : - en-US ft:publication_title : - Australia API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # screen --- DOM queries # screen --- DOM queries {#ariaid-title1} Release version: Australia Updated June 25, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 \. 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 {#r_run_ui_test_script_screen__section_variants} Each query type comes in the following variants. {#r_run_ui_test_script_screen__table_k2m_zmh_sjc__entry__4} | 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 | [Table 1. Query method variants] {#r_run_ui_test_script_screen__table_k2m_zmh_sjc} 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 {#r_run_ui_test_script_screen__section_query_types} Each variant supports the following query types. {#r_run_ui_test_script_screen__section_query_types__entry__3} | 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 `