Script helper functions

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