Troubleshooting

  • 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 Troubleshooting Run UI Test Script Step in Australia Release

    This guide helps ServiceNow customers resolve common issues encountered during theRun UI Test Scriptstep in Automated Test Framework (ATF) within the Australia release. It addresses errors such as reference errors, element detection failures, step timeouts, comparison failures, and impersonation problems to improve test reliability and accuracy.

    Show full answer Show less

    Handling user.type Timeouts in Workspace Inputs

    In some Workspace input components (e.g., SOW inputs), the user.type() function may stall indefinitely due to network activity delays, causing step timeouts. As a targeted workaround, set input values directly using native browser DOM APIs instead of user.type(). This approach should be used only when necessary, while user.type() remains the preferred method in other contexts.

    ReferenceError Issues

    Reference errors occur when variables or functions are undefined. Common causes include:

    • Using waitForElementToBeRemoved incorrectly—use snatf.waitForElementToBeRemoved(el) instead.
    • Using a nonexistent fill function—replace with user.type(el, text) or user.clear(el) followed by user.type(el, text).

    Element Not Found

    If elements are not found during testing:

    • Check if the element resides inside a shadow root; screen. queries support shadow DOM.
    • Use screen.debug() to inspect the DOM structure.
    • Prefer asynchronous findBy queries that poll for elements instead of synchronous getBy queries.
    • If visibility issues occur, fallback to using getBySelector with CSS selectors.

    Step Timeout Management

    The default timeout for steps is 30 seconds, which may be insufficient for slow navigations or network requests. To address this:

    • Increase the step timeout in the test record as needed.
    • Extend default 5-second timeouts for findBy queries by passing a { timeout: 15000 } option.
    • Ensure all Promises within the test script are properly awaited to prevent premature step completion.

    Comparison Failures

    When comparing values with steps() or params(), always use the == operator or convert values with String() to avoid failures. Refer to the Script Helper Functions documentation for detailed comparison behavior.

    Impersonation Failures

    For impersonation steps to succeed, the ATF runner must have the impersonator role assigned. Verify that the user identifier (sysid or username) is correct; error messages include the resolved ID for troubleshooting. The test runner automatically restores the original session after impersonation, even on timeouts, ensuring session integrity.

    Resolve common issues with the Run UI Test Script step, including reference errors, elements that aren't found, step timeouts, comparison failures, and impersonation failures.

    user.type times out on a Workspace input
    In certain Workspace (SOW) input components, user.type() can stall waiting for network activity that never completes, causing the step to time out. When this occurs, set the field value through the native browser DOM APIs directly. This approach is not part of the ATF testing library — it relies on standard web platform APIs available to any browser-side script — and should be treated as a targeted workaround rather than a general pattern. Prefer user.type() for all other contexts.
    const input = screen.getByRole('searchbox', { name: 'Caller' });
await user.click(input);

const nativeSetter = Object.getOwnPropertyDescriptor(
  HTMLInputElement.prototype,
  'value'
).set;

nativeSetter.call(input, 'Abel Tuter');
input.dispatchEvent(
  new InputEvent('input', {
    bubbles: true,
    composed: true,
    inputType: 'insertText',
  })
);
input.dispatchEvent(
  new Event('change', { bubbles: true, composed: true })
);

const host = input.getRootNode?.()?.host;
if (host) {
  host.dispatchEvent(
    new InputEvent('input', { bubbles: true, composed: true })
  );
  host.dispatchEvent(
    new Event('change', { bubbles: true, composed: true })
  );
}
    ReferenceError: X is not defined
    When a variable name isn't recognized, the error message lists all available APIs. The most common causes are:
    • waitForElementToBeRemoved — Use sn_atf.waitForElementToBeRemoved(el), not a top-level function.
    • fill — There is no fill function. Use user.type(el, text), or user.clear(el) and then user.type(el, text).
    Element not found
    • The element might be inside a shadow root. All screen.* queries pierce shadow roots. If the element still isn't found, use screen.debug() to inspect the DOM.
    • The element might not yet exist. Use findBy*, which is async and polls, instead of getBy*, which is synchronous and throws immediately.
    • The element might exist but not be visible to the query type. Use getBySelector with a CSS selector as a fallback.
    Step times out
    • The default timeout is 30 seconds. If your test involves slow navigations or network requests, configure a longer timeout on the step record.
    • A findBy* query waits up to 5 seconds by default before failing. Pass { timeout: 15000 } in the second argument to extend it, for example screen.findByRole('button', { name: 'Save', timeout: 15000 }). Timeout must go inside the second argument alongside name.
    • Ensure that all Promises are awaited. An unawaited Promise silently discards its result, and the step might resolve before the action completes.
    Comparison with steps() or params() always fails
    Use == or String() for comparisons. See the 'Comparison behavior' section in Script helper functions for more information.
    Impersonation fails
    • The ATF runner session requires the impersonator role.
    • Verify that the user identifier, sys_id or user_name, is correct. The error message includes the resolved ID.
    • The step restores the session on exit, including on timeout, so a session that isn't restored after a test failure doesn't occur in practice.