ATF

What It Is

ATF is ServiceNow's native testing automation platform that creates, executes, and manages automated tests across your entire instance. It solves the critical problem of validating functionality without manual intervention — whether you're testing form interactions, workflow execution, integration endpoints, or complex business logic. ATF operates at the platform level, intercepting and validating system behavior before it reaches end users. Unlike external testing tools that simulate user actions from outside ServiceNow, ATF runs within the platform itself, giving it direct access to the database, session context, and internal APIs that external tools cannot reach.

Architecturally, ATF lives in the Automated Test Framework application (scope: sn_atf) and integrates deeply with Studio, Update Sets, and the application lifecycle. The framework consists of test definitions stored in the sys_atf_test table, test steps in sys_atf_step, and execution results in sys_atf_test_result. Test execution happens through a dedicated runner service that can operate in browser mode (using actual browser instances) or headless mode (for faster execution without UI rendering). The framework hooks into ServiceNow's transaction pipeline, allowing it to validate database changes, business rule execution, and workflow progression in real-time.

ATF becomes indispensable in three scenarios: custom application development where manual regression testing becomes impossible to scale, instance upgrades where you need to validate that existing functionality still works after platform changes, and integration testing where you must verify that external systems interact correctly with ServiceNow. Without ATF, you're manually clicking through forms, checking field calculations, and validating workflow states every time you make changes — a process that becomes completely unmanageable once you have more than a handful of customizations. The framework also becomes critical for organizations practicing continuous integration, where code changes need automated validation before deployment to production.

Platform owners and application developers typically create and maintain ATF tests, while system administrators run test suites during upgrades and deployment cycles. Developers write tests as they build features, embedding test creation into their development workflow through Studio integration. System administrators inherit these tests and execute them during maintenance windows, upgrade testing, and troubleshooting scenarios. The division of responsibility usually places test creation with developers who understand the business logic, while test execution and results analysis falls to administrators who manage the platform lifecycle.

Recent ServiceNow releases have significantly enhanced ATF capabilities, particularly around API testing and headless execution performance. Vancouver introduced improved REST API testing steps and better integration with DevOps pipelines through enhanced CI/CD connectors. Xanadu added more sophisticated UI interaction capabilities, including better handling of Service Portal testing and improved support for complex form interactions. The framework has also gained better error reporting and test result visualization, making it easier to diagnose failures and understand test coverage across your applications.

The business impact of ATF extends beyond just catching bugs — it fundamentally changes how organizations approach ServiceNow development by enabling faster iteration cycles and reducing the risk of production incidents. Teams that effectively implement ATF can deploy changes more frequently with higher confidence, while organizations without automated testing often find themselves locked into lengthy manual testing cycles that slow innovation. The framework also provides valuable documentation of expected system behavior, serving as executable specifications that describe how your applications should function under various conditions.

Where to Find and Configure It

The primary ATF interface lives at System Applications > Studio where you create and manage tests within the context of your applications. Inside Studio, access the Tests tab to create new tests, view existing ones, and organize them into logical groups. You can also reach ATF directly through System Definition > Automated Test Framework for a comprehensive view of all tests across your instance.

Test execution happens through System Definition > Automated Test Framework > Run Test Suite where you select which tests to execute and configure execution parameters. View test results and execution history at System Definition > Automated Test Framework > Test Results to analyze failures, review execution times, and track test success rates over time. The Test Suite module lets you organize tests into logical collections for batch execution during specific scenarios like upgrade testing or release validation.

Access the underlying data model through System Definition > Tables and filter for tables starting with sys_atf to see test definitions, steps, and results. The sys_atf_test table contains your test definitions, while sys_atf_step holds individual test steps and their configurations. For advanced troubleshooting, examine sys_atf_test_result_step to see exactly which steps passed or failed during test execution and review detailed error messages.

How It Works Step by Step

ATF operates by executing a sequence of predefined steps within a controlled ServiceNow session, capturing system state at each step and comparing results against expected outcomes. When you trigger a test, ATF creates an isolated execution context that mimics a real user session but with enhanced monitoring capabilities to track database changes, business rule execution, and UI state transitions. The framework maintains detailed logs of every action performed and every validation checked, building a complete audit trail of system behavior during test execution.

Test steps execute in strict sequential order, with each step's success or failure determining whether the test continues or aborts. The framework supports complex conditional logic through step conditions and can branch test execution based on runtime values or system state. ATF's integration with the ServiceNow transaction pipeline allows it to validate not just final outcomes but intermediate states — ensuring that business rules fire correctly, approval workflows trigger as expected, and field calculations produce accurate results throughout the entire process flow.

The Execution Pipeline

1. ATF initializes a test execution context with a dedicated user session and transaction scope
2. The test runner loads the test definition from sys_atf_test and retrieves all associated steps from sys_atf_step
3. Each step executes in sequence, with ATF monitoring database transactions, UI events, and business logic execution
4. Step validation occurs immediately after each action, comparing actual results against expected outcomes defined in the step configuration
5. Test execution results, including detailed step-by-step outcomes and error messages, are written to sys_atf_test_result and related tables
6. The test session is cleaned up, rolling back any database changes unless the test is configured to persist data modifications

// Example: Custom ATF step to validate incident assignment logic
(function executeRule(current, previous /*null when async*/) {
    // Set up test data
    var incident = new GlideRecord('incident');
    incident.initialize();
    incident.short_description = 'ATF Test Incident';
    incident.assignment_group = '287ebd7da9fe198100f92cc8d1d2154e'; // Hardware group
    incident.priority = '3';
    
    // Execute the business logic being tested
    var sysId = incident.insert();
    
    // Reload to get any changes from business rules
    incident.get(sysId);
    
    // Validate expected behavior
    if (incident.assigned_to.nil()) {
        gs.addErrorMessage('Test Failed: Incident should have been auto-assigned');
        return false;
    }
    
    // Clean up test data
    incident.deleteRecord();
    return true;
})(current, previous);

Real-World Scenarios

Testing Incident Auto-Assignment Business Rules

Your organization has complex business rules that automatically assign incidents to specific technicians based on category, location, and workload balancing. Manual testing of every combination becomes impossible as your assignment logic grows more sophisticated.

Create a test with multiple Record Insert steps that create incidents with different category/location combinations, followed by Record Query steps that validate the assigned_to field contains the expected technician. Use Server Test steps for complex validation logic that queries user availability or calculates workload distribution. Include Record Delete steps at the end to clean up test data and prevent clutter in your incident table.

Validating Service Portal Form Submissions

You've built a custom Service Portal page for requesting laptop equipment with dynamic field visibility and client-side validation. The form needs to work correctly across different user roles and properly create both the request record and related approval workflows.

Build tests using Open URL steps to navigate to your Service Portal page, followed by Set Field Value steps to populate form fields and UI Action (Click Button) to submit the form. Use Field Validation steps to verify dynamic field behavior and Record Query steps to confirm the request was created with correct values. Include separate test runs with different user contexts by setting the Run As User property on your test definition.

REST API Integration Testing

Your ServiceNow instance exposes REST APIs for external applications to create and update incident records. These APIs include custom business logic for data validation and integration with third-party systems that must function reliably.

Create tests using REST API Test steps to send HTTP requests to your endpoints with various payloads and authentication scenarios. Configure the HTTP Method (POST, PUT, GET), Request Body with JSON payloads, and Expected Response Code for validation. Follow API calls with Record Query steps to verify that database records were created or updated correctly and that any triggered workflows completed as expected. Test both success scenarios and error conditions by sending invalid data and verifying appropriate error responses.

The Classic Mistake

// BAD: Hardcoded sys_ids that won't exist in other instances
(function(outputs, steps, stepResult, assertEqual) {
    
    var gr = new GlideRecord('incident');
    gr.get('a9e30c7dc61122760116cd4b8b40dd36'); // Hardcoded sys_id
    
    assertEqual('New', gr.getValue('state'), 
        'Expected incident state to be New');
    
    // Another bad pattern - assuming specific user exists
    var userGR = new GlideRecord('sys_user');
    userGR.get('6816f79cc0a8016401c5a33be04be441'); // Admin user sys_id
    
    gr.setValue('assigned_to', userGR.getUniqueValue());
    gr.update();
    
})(outputs, steps, stepResult, assertEqual);

This fails because ATF tests must be portable across instances, and hardcoded sys_id values are instance-specific. When the test runs in a different environment, ServiceNow can't find the referenced records, causing GlideRecord.get() to return false and subsequent operations to fail silently or throw errors. The test appears to pass in development but fails mysteriously in test or production instances. ServiceNow's ATF framework expects tests to create their own data or use reliable query patterns, not assume pre-existing records with specific identifiers.

// GOOD: Create or query for records dynamically
(function(outputs, steps, stepResult, assertEqual) {
    
    // Create test data dynamically
    var incident = new GlideRecord('incident');
    incident.initialize();
    incident.setValue('short_description', 'ATF Test Incident ' + gs.generateGUID());
    incident.setValue('caller_id', gs.getUserID()); // Current user
    var incidentId = incident.insert();
    
    // Store for cleanup or later steps
    outputs.test_incident_id = incidentId;
    
    // Query for admin user reliably
    var adminUser = new GlideRecord('sys_user');
    adminUser.addQuery('user_name', 'admin');
    adminUser.query();
    if (adminUser.next()) {
        incident.setValue('assigned_to', adminUser.getUniqueValue());
        incident.update();
    }
    
})(outputs, steps, stepResult, assertEqual);

When to Use This vs Alternatives

ATF is the right choice when you need comprehensive, repeatable testing that covers UI interactions, business logic validation, and integration workflows across multiple ServiceNow components. It's specifically designed for testing ServiceNow platform functionality where you need to verify that customizations work correctly after upgrades, configuration changes, or deployments.

Use ATF When You Need Platform-Aware Testing

Choose ATF when testing ServiceNow-specific functionality like Business Rules, UI Policies, ACLs, or Workflow activities where external tools like Selenium can't access the platform's internal state. ATF understands ServiceNow's session management, GlideRecord operations, and can validate server-side logic execution in ways that browser automation tools cannot. It's essential for testing upgrade compatibility and ensuring customizations don't break core platform functionality.

Use External Tools for Complex UI Scenarios

Switch to Selenium, Cypress, or Playwright when you need advanced browser automation like drag-and-drop operations, complex mouse interactions, or testing across multiple browser tabs. ATF's UI testing capabilities are limited to basic form interactions and can't handle sophisticated JavaScript widgets or third-party integrations embedded in ServiceNow pages. External tools also provide better reporting and can integrate with CI/CD pipelines more easily than ATF's native reporting.

Combine ATF with API Testing for Complete Coverage

Use ATF alongside dedicated API testing tools like Postman or REST Assured when testing complex integrations that involve both ServiceNow internal logic and external system interactions. ATF excels at testing the ServiceNow side of integrations (Business Rules firing, Transform Maps executing) while external tools better handle authentication schemes, response validation, and load testing of REST APIs. This combination ensures both the platform logic and external interfaces work correctly together.

Platform Interactions & Side Effects

• ATF test executions create records in sys_atf_test_result and sys_atf_test_result_step tables, with full audit trails of each test step's success or failure
• Business Rules fire normally during ATF execution unless explicitly bypassed with gs.setProperty('glide.record.legacy_cross_scope_access', 'true') or workflow context manipulation
• Email notifications are suppressed by default during test execution through the glide.email.send.enabled property being temporarily set to false
• ACL evaluations occur normally during ATF test runs, potentially causing tests to fail if the Run As User doesn't have proper permissions to the tested records or tables
• Update Sets capture ATF test definitions but not test results, meaning tests created in development must be manually recreated or imported via XML in target instances
• Session timeout settings in glide.ui.session_timeout can cause long-running test suites to fail when the test user's session expires mid-execution
• Transform Maps and Import Sets execute normally during ATF tests, potentially creating unintended data if tests trigger integration workflows
• Performance analytics and metrics collection continue during test execution, potentially skewing dashboard data with test-generated records
• Scheduled jobs and business rule async processing can interfere with test timing, causing race conditions where tests complete before background processing finishes
• Database transaction isolation means ATF tests can't reliably test scenarios involving multiple concurrent users or overlapping record modifications

Debugging and Troubleshooting

ATF test failures typically manifest as either step-level errors visible in the Test Results interface or silent failures where tests pass but don't actually validate the expected behavior. Users see generic "Test Failed" messages while the underlying issue might be permission errors, timing problems, or incorrect element selectors. The most common symptom is tests that work in development but fail in other instances due to environment-specific data or configuration differences.

Primary debugging locations include System Logs > System Log > All for JavaScript errors and System Diagnostics > Session Debug > Debug Business Rules to trace server-side execution during test runs. The ATF Test Result record contains detailed step-by-step execution logs with timestamps and variable values. Enable the com.glideapp.atf.log_level property set to 'debug' to capture additional detail about test execution flow and variable assignments.

Look for specific error patterns like "Element not found" indicating UI timing issues, "Permission denied" suggesting ACL problems, or "Record not found" pointing to hardcoded sys_id references. Browser console errors during UI tests often reveal JavaScript exceptions that don't appear in ServiceNow logs. Step output variables showing null or unexpected values typically indicate incorrect field references or scope issues within test scripts.

Diagnostic Checklist

• Verify the Run As User has necessary roles and ACL permissions for all tables and records involved in the test
• Check System Properties > ATF for timeout settings and enable verbose logging with com.glideapp.atf.log_level=debug
• Run individual test steps manually to isolate failures and verify step output variables contain expected data
• Review browser console during UI test execution for JavaScript errors not captured in ServiceNow logs
• Validate all hardcoded references (sys_ids, user names, table names) exist in the target instance
• Test with Business Rules and Workflow disabled to isolate base functionality from customization interference
• Check session timeout settings if tests fail during long-running suites or after periods of inactivity

Quick Reference

• ATF tests have a default timeout of 30 seconds per step, configurable via com.glideapp.atf.test.timeout system property
• Test suites can contain maximum 100 tests, and individual tests can have up to 1000 steps before performance degrades significantly
• UI tests running in headless mode cannot execute file upload operations or interact with browser dialogs
• ATF server-side steps execute in the global application scope regardless of the test's application scope setting
• Test result records in sys_atf_test_result are automatically deleted after 90 days via scheduled cleanup job
• Form UI tests fail if the target table has mandatory fields not populated by the test script, even if UI policies hide them
• Concurrent test execution is limited to 5 simultaneous test runs per instance to prevent resource exhaustion
• REST API test steps automatically handle authentication using the test runner's session, bypassing external authentication mechanisms
• ATF tests cannot validate email content directly but can verify notification records created in sysevent_email_action table during execution
• Cross-scope application testing requires the atf_test_admin role and explicit application access configuration in target scoped apps