Run the UI Test Script
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. For more examples about how to use the test script, see UI Test Script examples.
Input fields
| 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`. |
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
To add a script to a text:
- Open your test record and click Add test step.
- In the step picker, select the UI category and choose Run UI Test Script.
- Write your script in the Script field.
- Save the test step.
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.