ServiceNow Testing

ServiceNow Testing with ATF: Automated Test Framework Guide

HelpMeTest

HelpMeTest

— 8 min read
ServiceNow Testing with ATF: Automated Test Framework Guide

ServiceNow has evolved from an IT service management tool into a full enterprise workflow platform. Organizations now run HR case management, legal service delivery, customer service, security operations, and facilities management on ServiceNow — often with extensive customizations built on the platform's scripting and low-code capabilities. With this complexity comes significant testing risk: a misconfigured business rule or a broken UI policy can silently break processes that hundreds of employees depend on every day.

ServiceNow's Automated Test Framework (ATF) is the platform's native answer to this problem. Built directly into the Now Platform, ATF lets you create, manage, and execute automated tests without leaving ServiceNow. This guide explains how ATF works, how to build effective test suites, and how to integrate automated testing into your ServiceNow development and deployment lifecycle.

What Is ServiceNow ATF?

ATF is a testing tool embedded in ServiceNow that enables automated regression testing of your ServiceNow instance. Unlike external tools that interact with ServiceNow through a browser, ATF runs inside the platform and has direct access to ServiceNow's server-side APIs, business rules, and data model.

This architectural choice has significant implications. ATF tests can validate server-side logic — business rules, script includes, workflow activities — not just the user interface. And because ATF tests run in the platform itself, they work reliably across upgrades (ServiceNow upgrades don't change ATF's internal APIs the way they might change DOM structure).

Core ATF Concepts

Test: The basic unit of ATF. A test is a sequence of steps that simulate a user or system action and then assert that the expected outcome occurred. Tests can interact with the UI, call APIs, or execute server-side scripts.

Test step: An individual action within a test — clicking a button, filling in a form field, calling a REST API, or running a script. ATF provides a library of step types covering most common ServiceNow interactions.

Test suite: A collection of tests grouped together. Suites can be organized by module, by process, or by deployment scope. Suites can also contain other suites, allowing hierarchical organization.

Test runner: The execution engine for ATF tests. The test runner can execute individual tests, full suites, or scheduled runs. For UI tests, the test runner controls a headless browser within ServiceNow.

Scheduled test suite: A test suite configured to run automatically on a schedule (e.g., nightly regression) or triggered by a deployment event.

Setting Up ATF

ATF comes installed on every ServiceNow instance but needs to be activated and configured before use.

Activation and Permissions

Navigate to System Applications → All Available Applications and search for "Automated Test Framework." Install the ATF plugin. Once installed, the Automated Test Framework module appears in the navigator.

Grant the atf_test_designer role to users who will create and manage tests. Grant atf_test_runner to users who only need to execute tests. The admin role inherits both.

Test Instance Configuration

ATF tests that modify data should run against an isolated sub-production instance, not against your production instance. The standard ServiceNow instance hierarchy — Development → Test → Production — maps naturally to ATF usage:

  • Write and debug tests in Development
  • Run automated regression in Test before promoting changes to Production
  • Run smoke tests in Production after deployments complete

For CI/CD integration, configure ATF to run against a dedicated test instance that mirrors production data (or uses synthetic test data) but is isolated from real users.

Creating Your First Test

A well-structured ATF test follows the Arrange-Act-Assert pattern, adapted for ServiceNow:

  1. Arrange: Create or locate test records, set up prerequisites
  2. Act: Perform the action under test (submit a form, trigger a workflow, call an API)
  3. Assert: Verify the expected state — record values, workflow stage, notification sent

Example: Testing an Incident Workflow

Here's a test that verifies the incident escalation workflow fires correctly when a P1 incident is created:

Test Name: Incident_P1_Escalation_Triggers_On_Create

Steps:

  1. Impersonate User — step type: Impersonate. Impersonate a user with the itil role to simulate realistic permissions.
  2. Open Incident Form — step type: Open a URL or Record. Navigate to incident.do?sys_id=-1 (new incident form).
  3. Set Priority — step type: Set Field Values. Set Priority to 1 - Critical, Category to Software, Short Description to ATF Test - P1 Escalation Test.
  4. Submit Form — step type: Submit. Click the Submit button.
  5. Assert Record Created — step type: Check Field Value. Verify that an incident record was created with the expected field values.
  6. Assert Escalation Group Assigned — step type: Check Field Value. Verify that Assignment Group was populated by the business rule.
  7. Assert Notification Sent — step type: Assert Email Sent. Verify that an escalation email was sent to the major incident team.

Important: ATF runs steps sequentially. Use the "On failure" setting on each assertion step to control whether the test continues or stops when an assertion fails.

Parameterizing Tests

Hardcoded values in tests make maintenance painful. ATF supports test step inputs that can be parameterized, allowing you to reuse the same test logic with different data:

// In a "Run Server Side Script" step, access step inputs:
var incidentSysId = steps['Create Incident'].output.sys_id;
var gr = new GlideRecord('incident');
gr.get(incidentSysId);

// Assert with dynamic data
var assert = sn_atf.Assert;
assert.equals(gr.state, inputs.expected_state,
    'Incident state should be ' + inputs.expected_state);

Building Test Suites for Regression Coverage

Individual tests are only useful when organized into suites that cover your critical processes systematically.

Suite Structure by Business Domain

Organize suites by ServiceNow application area, mirroring how your instance is structured:

ServiceNow Regression Suite
├── ITSM Suite
│   ├── Incident Management Tests
│   │   ├── Incident_Create_P1_Escalation
│   │   ├── Incident_Resolve_CSAT_Survey_Trigger
│   │   └── Incident_Reopen_After_Resolve
│   ├── Change Management Tests
│   │   ├── Change_Emergency_Approval_Flow
│   │   └── Change_CAB_Meeting_Schedule
│   └── Problem Management Tests
├── HR Service Delivery Suite
│   ├── Onboarding_New_Employee_Workflow
│   └── Leave_Request_Approval_Chain
└── Custom Application Suite
    ├── Vendor_Portal_Submission
    └── Asset_Request_Fulfillment

Test Data Management

ATF tests that create records must also clean up after themselves. Use ATF's built-in cleanup mechanism or a dedicated cleanup step at the end of each test:

// Cleanup step — "Run Server Side Script"
var testRecordSysId = steps['Create Test Incident'].output.sys_id;
if (testRecordSysId) {
    var gr = new GlideRecord('incident');
    if (gr.get(testRecordSysId)) {
        gr.deleteRecord();
        gs.info('ATF Cleanup: Deleted test incident ' + testRecordSysId);
    }
}

Alternatively, use ATF's rollback feature — mark test steps as "rollback on completion" and ServiceNow will automatically undo database changes made during the test. This is the cleanest approach but not available for all step types.

Custom UI Testing in ATF

ATF's UI test capabilities are built on a headless browser that runs within ServiceNow. Custom UI pages, portal widgets, and Service Portal applications can be tested through ATF's UI test steps.

Testing Service Portal Widgets

Service Portal widgets present specific testing challenges because they run in Angular (AngularJS) and the rendered HTML differs significantly from the standard ServiceNow UI.

// In a "Run Client Side Script" step for Service Portal testing
// Wait for widget to finish loading
var deferred = $.Deferred();
var checkInterval = setInterval(function() {
    var widget = angular.element('[data-widget-id="your-widget"]').scope();
    if (widget && widget.data && widget.data.loaded) {
        clearInterval(checkInterval);
        deferred.resolve(widget);
    }
}, 100);

deferred.promise.then(function(widget) {
    // Now assert on widget state
    atf.assert.equals(widget.data.items.length, 3, 'Widget should show 3 items');
});

Testing Custom Forms and UI Policies

ATF can validate that UI policies behave correctly — fields becoming mandatory, visible, or read-only based on other field values:

Test: Change_Request_Risk_Makes_Fields_Mandatory
Steps:
1. Open Change Request form (new record)
2. Set Risk field to "High"
3. Assert: Justification field is mandatory (Check Field Mandatory)
4. Assert: Risk impact explanation field is visible (Check Field Visible)
5. Set Risk field to "Low"
6. Assert: Justification field is not mandatory

Integration Testing with ATF

ServiceNow rarely operates in isolation. Integration testing must cover the connections to external systems — CMDB syncs from discovery tools, ITSM integrations with monitoring platforms, and REST/SOAP APIs consumed by other enterprise applications.

REST API Testing

ATF includes a REST step type that lets you test ServiceNow's REST APIs directly:

Test: Incident_REST_API_Create_Returns_201

  1. REST Step — Method: POST, URL: /api/now/table/incident, Body: JSON with required fields
  2. Assert Status Code — Verify response code is 201
  3. Assert Response Body — Verify result.sys_id is present in the response
  4. Cleanup — Delete the created incident record

For outbound integrations — where ServiceNow calls external REST APIs — use ATF's mock server capability to simulate the external system's responses:

// In test setup: configure mock response for external API call
var mockServer = sn_atf.MockServer;
mockServer.respond('/api/external/ticketing/create', 200, {
    id: 'EXTERNAL-12345',
    status: 'created'
});

MID Server and Discovery Testing

For organizations using ServiceNow Discovery, testing that discovery patterns correctly identify and classify CIs requires an active MID Server in the test environment. ATF tests can trigger discovery runs and then assert on the resulting CMDB state.

CI/CD Integration with ServiceNow

Modern ServiceNow development practices use the Now Platform's Application Repository and Automated Test Framework together to implement a full CI/CD pipeline.

Using ATF with CI/CD Spoke

The ServiceNow CI/CD GitHub Actions integration (or the equivalent for Azure DevOps, GitLab, and Jenkins) can trigger ATF test runs as part of a deployment pipeline:

# GitHub Actions workflow for ServiceNow deployment
name: ServiceNow CI/CD

on:
  push:
    branches: [main]

jobs:
  deploy-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Apply Changes to Dev
        uses: ServiceNow/sncicd-apply-changes@v2
        with:
          app-sys-id: ${{ vars.APP_SYS_ID }}
        env:
          SN_INSTANCE_URL: ${{ secrets.SN_DEV_URL }}
          SN_CI_CD_TOKEN: ${{ secrets.SN_CI_CD_TOKEN }}

      - name: Run ATF Test Suite
        uses: ServiceNow/sncicd-run-atf@v2
        with:
          suite-sys-id: ${{ vars.REGRESSION_SUITE_SYS_ID }}
          browser: chrome
        env:
          SN_INSTANCE_URL: ${{ secrets.SN_DEV_URL }}
          SN_CI_CD_TOKEN: ${{ secrets.SN_CI_CD_TOKEN }}

      - name: Publish to Test Instance
        if: success()
        uses: ServiceNow/sncicd-publish-app@v2
        with:
          version-format: detect

The sncicd-run-atf action blocks the pipeline until the test suite completes and fails the pipeline if any tests fail. This creates a hard gate: changes that break regression tests cannot proceed to higher environments.

Handling ATF Results in Pipelines

ATF test results are stored in the sys_atf_test_run_step_result table. For CI/CD integration, the ATF APIs provide programmatic access to test results:

// REST API call to retrieve latest suite run results
GET /api/now/table/sys_atf_test_run_step_result?
    sysparm_query=sys_atf_test_run.parent=SUITE_SYS_ID^
                  sys_atf_test_run.state=complete^
    sysparm_limit=100&
    sysparm_fields=step_result,output_message,sys_atf_test

Extending ATF with External Testing

ATF is excellent for testing processes that live entirely within ServiceNow, but some scenarios require external validation:

  • Email notifications: Verifying that emails are actually received (not just that ServiceNow attempted to send them)
  • ITSM integrations: End-to-end verification that a ticket created in ServiceNow appears correctly in an external monitoring tool
  • Portal user experience: Rendering and interaction testing that validates the actual browser experience, not just the server-side state

For these scenarios, external testing tools that can interact with ServiceNow through its browser interface complement ATF's server-side strengths. Cloud-based testing platforms can handle the browser-facing portion while ATF validates internal state — the two approaches working together provide coverage that neither achieves alone.

HelpMeTest's natural language test creation, for example, makes it practical to build browser-level tests for ServiceNow portals without writing Selenium scripts from scratch. Teams can describe portal interactions in plain language, and the platform generates executable tests that run against the actual rendered portal — covering the user experience that ATF's server-side tests don't reach.

Best Practices for ATF at Scale

Name tests with the business process, not the technical action. Incident_P1_Escalation_Triggers_Notification is better than Test_Business_Rule_123. Names should communicate what breaks if the test fails.

Keep tests independent. Tests that depend on a previous test having run (or having created specific data) are fragile. Each test should set up its own prerequisites.

Run suites nightly, not just before deployments. Scheduled nightly runs catch regressions introduced by automated platform updates, MID Server changes, or configuration drift — things that don't trigger your deployment pipeline.

Review test failures before dismissing them. ATF test failures are sometimes caused by test data issues or environment inconsistencies rather than real code defects. But investigate each failure — it might be the defect you catch before it reaches production.

Maintain a coverage map. Track which business processes have ATF coverage and which don't. Gaps in coverage are deployment risks. Review and expand coverage with each major development cycle.

ServiceNow ATF is one of the more mature native testing frameworks in the enterprise platform space. Organizations that invest in building comprehensive ATF suites move faster, deploy more confidently, and spend less time on manual regression testing every time a new release or update arrives.

Read more