Script helper functions

  • Release version: Australia
  • Updated June 25, 2026
  • 2 minutes to read
    • Summarize
    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?)

    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 }
);
    Table 1. waitFor options
    Option Default Description
    timeout 5000 ms Maximum time to wait.
    interval 50 ms How often to retry.
    Note:

    screen.waitFor and the top-level waitFor are the same function.

    within(element) — scoped queries

    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

    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

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

    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