sys_atf_test Table — ServiceNow Reference

Table Reference/sys_atf_test

The `sys_atf_test` table stores Automated Test Framework (ATF) test definitions in the Development module. Records contain test steps as JSON, execution state, and pass/fail results—but test steps are stored as serialized objects that require careful parsing.

What This Table Is

The sys_atf_test table stores Automated Test Framework test definitions—the actual test cases that validate platform functionality. Each record represents a complete test scenario with its steps, configuration, and execution history. These aren't just test metadata; they're executable test definitions that the ATF engine runs against your instance.

This table belongs to the Development module and supports the entire ATF testing lifecycle—from test creation in the designer to execution in test suites to reporting results. The ATF uses this table to track which tests passed, failed, or were skipped during automated runs, making it central to continuous integration workflows.

The sys_atf_test table doesn't extend any other table—it's a standalone structure. However, it's closely related to sys_atf_test_result (execution results), sys_atf_test_suite (test groupings), and sys_atf_step (individual test step definitions).

In large enterprises, this table typically contains 500-2000 records representing the full test automation suite. Performance is generally good since test definitions are read frequently but written infrequently. The biggest performance consideration is parsing the test_definition JSON field, which can be substantial for complex tests with many steps.

When You'll Script Against This Table

You'll query sys_atf_test primarily in Scheduled Jobs that generate testing reports, Business Rules that trigger test runs based on deployment events, and Script Includes that build custom ATF dashboards. The most common pattern is creating automated reports that show test health across releases or identifying which tests consistently fail.

Access requires the atf_test_designer role to read test definitions and atf_test_admin to modify them. Most scripting happens in global scope since ATF functionality is platform-wide, not application-specific.

Generate test execution reports showing pass/fail rates by application or suite
Build custom dashboards that track test coverage across business processes
Identify tests that haven't run recently and may be obsolete
Automatically trigger test runs after deployments using deployment Business Rules
Parse test step definitions to extract which tables and fields are being tested
Clone and modify test definitions programmatically for similar business processes
Export test definitions for backup or migration to other instances

Table Gotchas

⚠️

The test_definition field contains serialized JSON that's not directly queryable. You can't use GlideRecord conditions to filter by specific test steps—you must retrieve the record and parse the JSON in JavaScript.

⚠️

The state field shows the test's execution status, but 'draft' tests can still be run manually. Don't assume state='active' is required for execution—check the last run date instead.

The expected_duration field is calculated from historical runs and gets updated after each execution, making it unreliable for new tests
ATF tests can reference other tests via the copied_from field, creating dependencies that aren't obvious from the test name alone
Deleting a test doesn't automatically clean up its results in sys_atf_test_result—you'll accumulate orphaned result records over time

⚠️

Performance degrades significantly when parsing test_definition JSON for large test suites. Cache parsed results or use GlideAggregate for counts rather than iterating through individual test steps.

The application field can be empty for tests that span multiple applications, making application-based reporting incomplete

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

The sys_atf_test_result table is your most common join—it stores the actual execution results for each test run. Every time a test executes, it creates a new result record with pass/fail status, execution time, and step-by-step outcomes. You'll almost always query both tables together when building test reports or dashboards.

The sys_atf_test_suite table groups tests into logical collections for batch execution, while sys_atf_test_suite_test creates the many-to-many relationship between suites and tests. When reporting on test coverage by functional area, you'll often join through these tables to group results by business process.

The sys_atf_step table defines the available test step types (like "Set field values" or "Run server script"), while sys_app provides application context for organizing tests by functional area. These relationships help when building comprehensive test coverage reports or identifying gaps in your automation strategy.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
name	string	Name	Test name displayed in ATF interface and reports. Must be unique within the application scope—duplicates cause execution conflicts.
state	choice	State	Test lifecycle state: draft, active, or retired. Draft tests can still execute manually, so don't rely on this for execution control.
test_definition	json	Test Definition	Serialized JSON containing all test steps and configuration. Not queryable with GlideRecord conditions—requires JavaScript parsing after retrieval.
description	string	Description	Free-text test description. Often contains business context that's crucial for maintenance but not captured in test steps.
application	reference	Application	References sys_app for application scope. Can be empty for tests spanning multiple apps, making app-based reporting incomplete.
expected_duration	integer	Expected Duration	Calculated from historical run times in seconds. Gets updated after each execution, so it's unreliable for new tests or scheduling.
copied_from	reference	Copied From	References another sys_atf_test if this test was cloned. Creates hidden dependencies between tests that affect maintenance.
table	string	Table	Primary table the test operates on. May not reflect all tables touched by complex tests with multiple record interactions.
active	boolean	Active	Boolean active flag independent of state field. Both must be considered when determining if a test should run automatically.
run_as	reference	Run As	User context for test execution. References sys_user—critical for tests that validate role-based access or assignment rules.
abort_on_failure	boolean	Abort on Failure	Whether test suite execution stops if this test fails. Affects suite-level reporting and can mask subsequent test failures.
version	string	Version	Test definition version for change tracking. Increments when test steps are modified but doesn't automatically archive old versions.
rollback_context	json	Rollback Context	JSON data for cleaning up test changes. Contains record IDs and state info—critical for understanding test data persistence.
runner_status	choice	Runner Status	Current execution status: ready, running, paused, completed. May be stale if test runner crashed during execution.
tags	string	Tags	Comma-separated tags for test categorization. Used by test suites for dynamic test selection but prone to typos and inconsistency.

Common Queries

Get all active ATF tests ready for execution

// Basic query for active tests - most common starting point
var gr = new GlideRecord('sys_atf_test');
gr.addQuery('active', true);
gr.addQuery('state', 'active');
gr.query();

while (gr.next()) {
    gs.info('Test: ' + gr.name + ', Expected duration: ' + gr.expected_duration + 's');
}

// Both active flag and state must be checked for execution readiness

Find tests by state and application for release validation

// Filter by state and application - common for release testing
var gr = new GlideRecord('sys_atf_test');
gr.addQuery('state', 'active');
gr.addQuery('application.name', 'Incident Management'); // Join to sys_app
gr.addQuery('runner_status', 'ready');
gr.orderBy('name');
gr.query();

while (gr.next()) {
    gs.info('Release test: ' + gr.name + ' (App: ' + gr.application.getDisplayValue() + ')');
}

Get tests with recent failures for maintenance review

// Find tests needing attention based on recent execution results
var gr = new GlideRecord('sys_atf_test');
gr.addQuery('active', true);
gr.addQuery('JOINsys_atf_test_result.test=sys_id');
gr.addQuery('sys_atf_test_result.status', 'failed');
gr.addQuery('sys_atf_test_result.sys_created_on', '>', gs.daysAgoStart(7));
gr.query();

while (gr.next()) {
    gs.info('Failing test: ' + gr.name + ' (Last run by: ' + gr.run_as.getDisplayValue() + ')');
}

Count tests by application using aggregate

// Aggregate test counts by application for coverage reporting
var ga = new GlideAggregate('sys_atf_test');
ga.addQuery('active', true);
ga.addAggregate('COUNT');
ga.groupBy('application');
ga.query();

while (ga.next()) {
    var appName = ga.application.getDisplayValue() || 'No Application';
    gs.info('Application: ' + appName + ', Test count: ' + ga.getAggregate('COUNT'));
}

Wrong way vs right way to check test execution history

// WRONG: This misses tests that have never run
var badQuery = new GlideRecord('sys_atf_test');
badQuery.addQuery('runner_status', 'completed'); // Only gets completed tests
badQuery.query();

// RIGHT: Check for tests without recent results
var gr = new GlideRecord('sys_atf_test');
gr.addQuery('active', true);
gr.addQuery('JOINsys_atf_test_result.test!=sys_id^ORsys_atf_test_result.sys_created_on<' + gs.daysAgoStart(30));
gr.query();

// This finds tests that never ran OR haven't run in 30 days

Related Tables

sys_atf_test_suite sys_user

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue