Automated Test Framework (ATF): Writing and Running Tests

Introduction

The Automated Test Framework (ATF) is ServiceNow's built-in testing platform. It enables developers and administrators to write repeatable, automated tests that validate platform behavior — catching regressions before they reach production. In mature ServiceNow practices, ATF tests run as part of every deployment pipeline.

---

ATF Architecture

Test Suite
    └─ Test (one scenario)
          └─ Test Step 1 (open a form)
          └─ Test Step 2 (set field values)
          └─ Test Step 3 (submit the form)
          └─ Test Step 4 (assert field value equals expected)

Components

Component	Description
Test Suite	Groups related tests for a feature or module
Test	A single testable scenario
Test Step	An individual action or assertion
Step Configuration	Reusable step template (form interaction, API call, assertion)
Test Runner	Executes tests and reports pass/fail

---

Built-In Step Configurations

ServiceNow provides dozens of pre-built step configurations:

UI Interaction Steps:

• Open a form record
• Set a field value
• Click a UI Action button
• Assert a field value
• Assert a field is visible/mandatory/read-only

Server-Side Steps:

• Run a server-side script with assertions
• Create/update/delete a record
• Assert GlideRecord conditions

API Steps:

• Call a REST endpoint
• Assert response status and body

---

Writing Your First Test

Scenario: When an incident's priority is set to 1 (Critical), the assignment group should auto-populate with "Major Incident Team".

Test: P1 Incident Auto-Assignment

Step 1: Open Incident Form (New record)
Step 2: Set field — Short description = "Test P1 Incident"
Step 3: Set field — Priority = 1 - Critical
Step 4: Assert field value — Assignment group = Major Incident Team
Step 5: Submit form
Step 6: Assert record field — State = In Progress

Step 4 in detail — Server-side assertion:

// In a "Run server-side script" step
var incidentSysId = steps[0].outputs.record_id;

var gr = new GlideRecord('incident');
gr.get(incidentSysId);

stepResult.setOutputVariable('assignment_group', 
    gr.getDisplayValue('assignment_group'));

if (gr.getDisplayValue('assignment_group') === 'Major Incident Team') {
    stepResult.setSuccess();
} else {
    stepResult.setFailed(
        'Expected "Major Incident Team", got "' + 
        gr.getDisplayValue('assignment_group') + '"'
    );
}

---

Test Data Management

ATF tests create real records in the database. Use Test Data step configurations to:

1. Create prerequisite records before the test
2. Clean them up after the test runs

Best practice: Always delete test records in a Cleanup step, even on test failure. Use unique identifiers (e.g., [ATF_TEST] prefix in short descriptions) so test records are easy to identify.

// Cleanup step — delete all ATF test records
var gr = new GlideRecord('incident');
gr.addQuery('short_description', 'STARTSWITH', '[ATF_TEST]');
gr.deleteMultiple();

---

Test Suites

Organize related tests into suites for parallel execution and reporting:

Incident Management Suite
  ├─ P1 Auto-Assignment Test
  ├─ Incident Creation Validation Test
  ├─ SLA Timer Start Test
  ├─ Resolution Fields Mandatory Test
  └─ Incident to Problem Escalation Test

Suites can be executed in sequence or in parallel (parallel requires ATF Agent).

---

Impersonation in Tests

Test behavior as different users to validate role-based logic and ACLs:

Step: Impersonate User
  User: test_service_desk_agent

Step: Open Incident Form
  (Now executing as the service desk agent)

Step: Assert field is read-only
  Field: Configuration item (not editable by agents)

---

Running ATF Tests

Manual Execution

Automated Test Framework > Tests → select test → Run Test

Scheduled Execution

Automated Test Framework > Scheduled Suites > New

Schedule suites to run nightly or after each deployment.

Integration with Pipeline

ServiceNow provides a REST API endpoint to trigger ATF runs programmatically, enabling integration with CI/CD pipelines (Jenkins, GitHub Actions, Azure DevOps):

POST /api/sn_cicd/testsuite/run
{
  "test_suite_sys_id": "abc123...",
  "browser_name": "Chrome",
  "browser_version": "latest"
}

---

Best Practices

• Write ATF tests before deploying Business Rules and Client Scripts
• Always include cleanup steps to delete test data
• Use impersonation to test role-specific behavior
• Run test suites in sub-prod after every Update Set import
• Keep test cases focused — one scenario per test
• Name tests descriptively: "P1 incident assigns to Major Incident Team"
• Don't test ServiceNow out-of-the-box behavior — test your customizations
• Target 100% of Business Rules with at least one ATF test

---

Conclusion

ATF transforms deployments from anxious manual checks into confident, automated validations. A well-maintained test suite is a living specification of how your customizations should behave. Invest in writing tests alongside your development work — not as an afterthought — and you'll catch regressions before your users do.