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


---

# sn_atf --- utility APIs

# sn_atf --- utility APIs {#ariaid-title1}

Release version: Australia  
Updated June 25, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 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 snatf --- utility APIs

Thesnatf APIoffers a set of utility methods designed for the Run UI Test Script step within ServiceNow Automated Test Framework (ATF).
These utilities facilitate navigation, page evaluation, user impersonation, file uploads, and interactions with shadow DOM elements in the tested iframe context.
This enables customers to create robust UI tests that interact with ServiceNow interfaces programmatically and efficiently.
Show full answer Show less  

## Navigation

* **snatf.navigate(url):** Navigate the iframe to a given relative or absolute URL and wait for full page load.
* **snatf.reload():** Reload the current page in the iframe.
* **snatf.goBack()/goForward():** Navigate backward or forward in the iframe's history.
* All navigation methods return promises that resolve after the page load event, with the screen object automatically retargeting to the new document body.
* **snatf.evaluate(fn, arg?):** Run JavaScript functions inside the iframe context with optional arguments, supporting asynchronous results, similar to Playwright's page.evaluate().

## User Impersonation

**snatf.impersonate(userId)** enables impersonating a user by their sysid or username for the duration of the test step. The iframe reloads automatically after impersonation, and the original session is restored after the step completes. This requires the ATF runner session to have the impersonator role. This feature allows tests to simulate different user roles securely and reliably.

## File Uploads

* **snatf.upload(source):** Upload files or copy existing attachments to the current classic form. The source can be a sysattachment sysid or a File object.
* Specialized upload methods support uploads within Workspace (**uploadInWS** ), Service Portal (**uploadInSP** ), and service catalog variables (**uploadInSCVariable** , **uploadInSPVariable**).
* These methods can infer the target table and record from the current URL if not explicitly provided.
* **snatf.getAttachmentFile(sysId):** Retrieves file bytes from a sysattachment record as a File object, facilitating reuse in uploads.
* Only some upload methods return detailed file info (sysId, name, size); others return void promises.

## DOM Utilities

* **snatf.querySelector(root, selector)** and **querySelectorAll(root, selector)** enable shadow-DOM-piercing element selection within the iframe, crossing shadow boundaries.
* **snatf.getActiveElement(root?)** returns the currently focused element, including inside shadow roots and iframes.
* **snatf.waitForElementToBeRemoved(element, opts?)** waits for a DOM element to be removed, resolving immediately if it's already disconnected.
* **snatf.delay(ms)** allows fixed pauses, though dynamic wait methods like waitFor or findBy are preferred.

## Practical Benefits for ServiceNow Customers

Using the snatf utility APIs, customers can script comprehensive UI tests that navigate ServiceNow pages, evaluate page content, impersonate users to test role-based functionality, and handle file uploads across various interfaces. The DOM utilities support reliable interaction with complex UI elements, including those within shadow DOMs. These capabilities improve test accuracy, maintenance, and automation efficiency within the ServiceNow testing ecosystem.  
The sn_atf API provides utility methods for a Run UI Test Script step: navigation, page evaluation, impersonation, file uploads, and shadow-DOM utilities.

## Navigation {#r_run_ui_test_script_sn_atf__section_navigation}

{#r_run_ui_test_script_sn_atf__section_navigation__entry__2}

| Method | Description |
|-|-|
| sn_atf.navigate(url) | Navigate the tested iframe to a URL, relative or absolute. Awaits full page load. |
| sn_atf.reload() | Reload the current page in the iframe. |
| sn_atf.goBack() | Go to the previous page in the navigation history managed by this step. |
| sn_atf.goForward() | Go to the next page in the navigation history. |
[Table 1. Navigation methods]

All navigation methods return Promises and resolve when the `load` event of the new page
fires. The `screen` object automatically retargets to the new document body after
navigation.

    await sn_atf.navigate('/now/nav/ui/classic/params/target/incident_list.do');
    const row = await screen.findByRole('row', { name: /INC0001234/ });
    await user.click(row);
    await screen.findByRole('heading', { name: /INC0001234/ });

## sn_atf.evaluate(fn, arg?) {#r_run_ui_test_script_sn_atf__section_evaluate}

Runs `fn` inside the JavaScript realm of the tested iframe and returns a Promise with the
result. This method mirrors the `page.evaluate()` contract in Playwright.

    // Read a value from the iframe's context
    const title = await sn_atf.evaluate(() => document.title);

    // Pass an argument into the iframe context
    const attr = await sn_atf.evaluate((sel) => document.querySelector(sel)?.dataset.state, '[data-testid="status"]');

The function is serialized through `.toString()` and evaluated in the iframe, so it can't
close over variables from the test script scope. Pass data through the `arg` parameter
instead.

`fn` can return a plain value or a Promise. When it returns a Promise,
`evaluate` awaits it.

## sn_atf.impersonate(userId) {#r_run_ui_test_script_sn_atf__section_impersonate}

Impersonates a user for the remainder of the step. Accepts a `sys_id` or
`user_name`. The iframe reloads automatically after impersonation succeeds, and the original
session is always restored when the step ends, whether the step passes, fails, or times out.

    await sn_atf.impersonate('fred.luddy');
    // Or by sys_id:
    await sn_atf.impersonate('6816f79cc0a8016401c5a33be04be441');

    // Now interact as that user
    const btn = await screen.findByRole('button', { name: 'Create Incident' });
    expect(btn).toBeEnabled();

Impersonation requires the ATF runner session to have the `impersonator` role.

## File uploads {#r_run_ui_test_script_sn_atf__section_uploads}

{#r_run_ui_test_script_sn_atf__section_uploads__entry__3}

| Method | Signature | Description |
|-|-|-|
| `sn_atf.upload(source)` | `upload(sysId | File)` | Upload to the current classic ServiceNow form. Pass a `sys_attachment` sys_id to copy server-side, with no bytes transferred, or pass a `File` object to upload through REST. |
| `sn_atf.uploadInWS(source, table?, sysId?)` | `uploadInWS(sysId | File, tableName?, recordSysId?)` | Upload to a Workspace record. `table` and `sysId` are inferred from the current URL when omitted. |
| `sn_atf.uploadInSP(source, table?, sysId?)` | `uploadInSP(sysId | File, tableName?, recordSysId?)` | Upload to a Service Portal form record. `table` and `sysId` are read from the URL query parameters when omitted. |
| `sn_atf.uploadInSCVariable(source, variableName)` | `uploadInSCVariable(sysId | File, variableName)` | Upload to a service catalog attachment variable in the classic catalog. `variableName` is the column name, for example `'proof_of_id'`. |
| `sn_atf.uploadInSPVariable(source, variableName, opts?)` | `uploadInSPVariable(sysId | File, variableName, { timeout? })` | Upload to a Service Portal catalog attachment variable. `variableName` is the column name without the `sp_formfield_` prefix. |
[Table 2. File upload methods]

sn_atf.upload() returns Promise\<void\>, not Promise\<{ sysId, name, size }\>. Only uploadInWS, uploadInSP, uploadInSCVariable, and uploadInSPVariable return { sysId, name, size }.

    // Copy an existing attachment to the current form (no bytes transferred)
    await sn_atf.upload('a1b2c3d4e5f67890a1b2c3d4e5f67890');

    // Upload a File retrieved from another attachment
    const file = await sn_atf.getAttachmentFile('a1b2c3d4e5f67890a1b2c3d4e5f67890');
    await sn_atf.uploadInWS(file);

## sn_atf.getAttachmentFile(sysId) {#r_run_ui_test_script_sn_atf__section_get_attachment_file}

Fetches the bytes of a `sys_attachment` record through the REST API and returns a
`Promise<File>` with the correct name and content type. Use this method to read an
attachment from one record and upload it to another.

    const file = await sn_atf.getAttachmentFile('a1b2c3d4e5f67890a1b2c3d4e5f67890');
    await sn_atf.upload(file);

## DOM utilities {#r_run_ui_test_script_sn_atf__section_dom_utilities}

{#r_run_ui_test_script_sn_atf__section_dom_utilities__entry__2}

| Method | Description |
|-|-|
| `sn_atf.querySelector(root, selector)` | Shadow-DOM-piercing `querySelector`. Finds the first element that matches `selector` under `root`, crossing shadow boundaries. |
| `sn_atf.querySelectorAll(root, selector)` | Shadow-DOM-piercing `querySelectorAll`. Returns all matching elements. |
| `sn_atf.getActiveElement(root?)` | Returns the currently focused element, piercing shadow roots and iframes. |
| `sn_atf.waitForElementToBeRemoved(element, opts?)` | Waits until `element` is removed from the DOM. Resolves immediately if the element is already disconnected. |
| `sn_atf.delay(ms)` | Returns a Promise that resolves after `ms` milliseconds. Prefer `waitFor` or `findBy*` for dynamic waits, and use `delay` only when a fixed pause is unavoidable. |
[Table 3. DOM utility methods]