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


---

# Script helper functions

# Script helper functions {#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 Script helper functions

The Run UI Test Script step in ServiceNow provides four global helper functions---waitFor,within,steps, andparams---which enhance UI test scripting by enabling polling, scoped queries, and accessing data from other parts of the test.
Show full answer Show less  

## Key Features

* **waitFor(callback, options?)** : Repeatedly polls a callback function until it stops throwing an error, useful for waiting on conditions not expressible by a single query. It accepts options for *timeout* (default 5000 ms) and *interval* (default 50 ms).
* **within(element)**: Restricts queries to a specific DOM subtree, helping disambiguate elements when the same text or role appears multiple times. For example, you can scope a button search within a form.
* **steps(stepSysId)**: Accesses output variables from a previously run test step by providing the sysid of the step record (not the step result). It returns a lazy Proxy that resolves field values, including dot-walked references, upon string coercion. It supports synchronous server calls to retrieve data and returns an empty string for unknown IDs or unresolved paths.
* **params(paramName)** : Reads parameter values from the active parameter set during test execution. Like `steps()`, it returns a lazy Proxy with support for dot-walking and returns an empty string if the test is not parameterized or the parameter is missing.

## Important Behavior Notes

* Both `steps()` and `params()` return ES6 Proxy objects, not plain strings. To correctly compare values, use string coercion methods such as `String()`, template literals, or the loose equality operator `==`.
* Strict equality comparisons (`===`) against string literals will always fail due to the Proxy object nature.
* Use the sysid of the step record (visible in the URL of the step record) when calling `steps()`.

## Practical Application for ServiceNow Customers

These helper functions enable more reliable, maintainable, and readable UI test scripts by providing:

* **Robust waiting mechanisms** for asynchronous UI states with `waitFor()`.
* **Precise element targeting** via `within()` to avoid ambiguous queries.
* **Easy access to prior step data** through `steps()`, enabling complex test flows that depend on earlier outputs.
* **Dynamic parameter handling** with `params()`, facilitating test data-driven scenarios.

By understanding and using these functions properly, you can create UI tests that are both flexible and tightly integrated with your test data and execution context.  
A Run UI Test Script step provides 4 global helper functions for polling, scoping queries, and reading data from other parts of the test: `waitFor`, `within`,
`steps`, and `params`.

## waitFor(callback, options?) {#r_run_ui_test_script_helpers__section_waitfor}

waitFor() polls `callback` repeatedly until it stops throwing. Use this function for conditions that aren't expressible as a single `findBy*` query.

    await waitFor(
      () => expect(screen.getByRole('progressbar')).not.toBeInTheDocument(),
      { timeout: 10000, interval: 200 }
    );

{#r_run_ui_test_script_helpers__section_waitfor__entry__3}

| Option | Default | Description |
|-|-|-|
| `timeout` | 5000 ms | Maximum time to wait. |
| `interval` | 50 ms | How often to retry. |
[Table 1. waitFor options]

Note:  
`screen.waitFor` and the top-level `waitFor` are the same function.

## within(element) --- scoped queries {#r_run_ui_test_script_helpers__section_within}

within() scopes all queries to a subtree. Use it to disambiguate when the same text or role appears multiple times on the page.

    const form = screen.getBySelector('form');
    const submitBtn = within(form).getByRole('button', { name: 'Submit' });
    await user.click(submitBtn);

## steps(stepSysId) --- access prior step outputs {#r_run_ui_test_script_helpers__section_steps}

steps() reads output variables from a previously run step in the same test. The argument is the sys_id of the step record, not the step result.

    // Read a flat output value
    const incidentSysId = String(steps('abc123def456...').record_sys_id);

    // Dotwalk through a reference field
    const deptName = String(steps('abc123def456...').assigned_to.department.name);

Behavior notes:

* Returns a lazy Proxy. No network call is made until the value is coerced to a string, through a template literal, `==`, `String()`, or string concatenation.
* Use `==` rather than `===` for comparisons. Strict `===` against a string literal doesn't match the Proxy object.
* Returns an empty string for unknown step IDs or unresolvable dotwalk paths.
* Resolves dotwalked, multi-segment paths through a synchronous server call on first access.

Note:  
`steps(SYS_ID)` takes the sys_id of the step record, not the step result. Find it in the URL when you open the step record.

## params(paramName) --- parameter set values {#r_run_ui_test_script_helpers__section_params}

params() reads a parameter value from the active parameter set when the test runs with a Test Data --- Parameter Set entry.

    // Read a simple parameter
    const username = String(params('username'));

    // Dotwalk through a reference field on the parameter value
    const deptName = String(params('assigned_to').department.name);

Behavior notes:

* Returns a lazy Proxy, with the same lazy resolution and caching behavior as `steps()`.
* Returns an empty string (`''`) when the test isn't parameterized or the named parameter doesn't exist.
* Use `==` rather than `===` for comparisons.

## Comparison behavior with steps() and params() {#r_run_ui_test_script_helpers__section_comparison}

steps() and params() return ES6 Proxy objects, not plain strings. Coercing them to a string works correctly, through template literals, `==`, or `String()`, but
strict equality (`===`) against a string literal is always `false`. This behavior is similar to the server-side `GlideElement`.

    // Correct
    if (String(steps('abc').state) === '1') { ... }
    if (steps('abc').state == '1') { ... }
    const val = `${steps('abc').state}`;

    // Does not work as expected
    if (steps('abc').state === '1') { ... } // always false