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


---

# Run the UI Test Script

# Run the UI Test Script {#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 Run the UI Test Script

The Run UI Test Script step allows ServiceNow customers to automate interactions with UI elements on classic and Now Experience pages.
This step supports navigation to records, field entry, button clicks, user impersonation, file uploads, and UI state assertions.
It leverages shadow-DOM-aware query APIs and realistic user-interaction simulation to execute tests within the browser context.
Show full answer Show less  

## Key Features

* **Async scripting with Promise support:** Scripts run automatically as async functions, supporting await for user interactions like clicks and typing.
* **Comprehensive APIs:** Includes DOM query methods (e.g., getByRole, findByText), navigation, evaluation, impersonation, file upload utilities, and user interaction commands.
* **Input configuration:** Allows setting execution order, activation status, application scope, timeout durations (default 30 seconds), and descriptive notes for each test step.
* **Test step addition:** Easily add the Run UI Test Script step to any test record via the UI test category, write your script, and save. The step runs inside an iframe within the Client Test Runner.

## Practical Use and Benefits

This capability enables customers to create robust automated UI tests that simulate realistic user behavior and validate UI elements across different page experiences. It helps ensure application quality by allowing detailed scripting of user flows and UI state checks within the ServiceNow platform.

By using this step, customers can:

* Automate complex UI interactions including navigation and impersonation.
* Verify UI conditions and element states reliably using assertions.
* Manage test execution order and timeouts for precise control.
* Enhance test coverage with utility APIs to interact with attachments and page content.  
Learn how to use the Run UI Test Script step to navigate to records, fill fields, click buttons, impersonate users, upload attachments, and assert UI state on classic and Now Experience pages.
The test script has access to shadow-DOM-aware query APIs, realistic user-interaction simulation, and utility APIs for navigation, page evaluation, impersonation, and file uploads. For an overview of the step and the scripting
APIs, see [Run UI Test Script Developer Guide](https://servicenow-prod.fluidtopics.net/pfmpYUSfh8LSpaXpS~~V0g "The Run UI Test Script test step runs a client-side test script in the browser to drive and verify the user interface with no server-side execution needed. Use this step to automate multi-step UI journeys on both classic and Now Experience pages, like navigating, filling fields, clicking, impersonating users, uploading attachments, and asserting page state."). For more examples about how to use the test script, see [UI Test Script examples](https://servicenow-prod.fluidtopics.net/F3JDy5InlZgDnAKoIgFPcw "Reference example scripts to use in a Run UI Test Script step.").

## Input fields {#r_run_ui_test_script__section_inputs}

{#r_run_ui_test_script__section_inputs__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer that specifies the order in which the test runs this step. As you create steps, the system assigns each step an incremental value so that the test runs steps in the order that you create them. To change the default order, edit the Execution order values. |
| Active | Option that activates this test step for use. |
| Application | Application scope in which the system runs this step. |
| Test | Read-only name of the test that you're adding the step to. |
| Step config | Read-only name of the step. |
| Description | Description of the test step. The system sets this value automatically from the field values of the test step. This field appears after you submit the test step. |
| Notes | Notes about the test step. |
| Timeout | Number of seconds allowed before the step fails. The default is 30. |
| Script | Test body to run. Available APIs: * `expect` assertions, * `screen`: DOM queries such as `getByRole`, `findByText`, and `getBySelector`. * `sn_atf`: `navigate`, `evaluate`, `upload`, `impersonate`, `getAttachmentFile`, `querySelector`, `delay`, and `waitForElementToBeRemoved`. * `user`: user interactions such as `click`, `type`, `keyboard`, `tab`, and `clear`. * Script helpers: `waitFor` (polling), `within` (scoped queries), `steps` (prior step outputs), `params` (parameter set values). * Element predicates: such as `isVisible`, `isEnabled`, and `hasClass`. Return a Promise or use `async`/`await`. {#r_run_ui_test_script__ul_hcy_mhh_sjc} |
[Table 1. Run UI Test Script input fields]

Note:  
The test script runs as an `async` function automatically. All element interactions, such as `user.click()` and `user.type()`, return Promises --- use `await`. A synchronous script that doesn't use `await` resolves automatically when the last statement runs.

## Add the step to a test {#r_run_ui_test_script__section_add_step}

To add a script to a text:

1. Open your test record and click Add test step.
2. In the step picker, select the UI category and choose Run UI Test Script.
3. Write your script in the Script field.
4. Save the test step.
{#r_run_ui_test_script__ol_cmt_n3h_sjc}

The step runs inside the browser context of the Client Test Runner. The tested page loads in an iframe,
and your script interacts with it through the scripting APIs.

For script test examples, see [UI Test Script examples](https://servicenow-prod.fluidtopics.net/F3JDy5InlZgDnAKoIgFPcw "Reference example scripts to use in a Run UI Test Script step.").