sys_atf_test_suite Table

Table Reference/sys_atf_test_suite

The `sys_atf_test_suite` table stores collections of ATF (Automated Test Framework) tests that run as coordinated groups. Owned by the Development module, it's essential for regression testing before deployments. The key thing to know: test suites execute asynchronously, so always check the `state` field before assuming completion.

What This Table Is

The sys_atf_test_suite table stores collections of ATF tests designed to run together as logical groups. Each record represents a test suite that can contain multiple individual tests (sys_atf_test records) and executes them in sequence or parallel. Test suites are the backbone of regression testing, allowing developers to validate entire features or applications before deployments.

Owned by the Development module, test suites support the full ATF lifecycle from creation to execution to result analysis. They integrate deeply with CI/CD pipelines through REST APIs and can be triggered manually, scheduled, or called programmatically. The table supports both simple linear test execution and complex dependency management between tests.

This table does not extend any parent table—it's a standalone entity. However, it has a many-to-many relationship with sys_atf_test records through the sys_atf_test_suite_test junction table. Test suite results are stored in sys_atf_test_result_suite, creating a clear audit trail of execution history.

In large enterprises, expect 100-500 test suite records with execution results scaling to thousands of records monthly. Test suite execution can be resource-intensive—a single suite with 50+ tests may run for 10-30 minutes. The table includes fields for execution tracking, dependency management, and performance metrics that become critical at scale.

When You'll Script Against This Table

You'll script against this table primarily in Business Rules that trigger suite execution based on deployment events, Script Includes that manage CI/CD integration, and Scheduled Jobs that run regression testing on schedules. ATF suite execution APIs are commonly wrapped in Script Includes for reusability across multiple contexts like release management workflows and automated deployment pipelines.

Access requires the atf_test_designer role for full CRUD operations, while atf_test_admin provides execution rights. Most scripting happens in global scope, but be aware that test execution itself can span multiple application scopes depending on what the individual tests are validating.

Common scripting patterns:

Trigger suite execution via sn_atf.ATF.executeTestSuite() API calls
Poll suite execution status by querying state field changes and sys_atf_test_result_suite
Build dynamic test suites by programmatically adding tests via sys_atf_test_suite_test records
Parse execution results and generate deployment reports based on pass/fail metrics
Schedule recurring regression tests using sysauto_script integration
Implement deployment gates that block releases until critical test suites pass
Create test suite templates for different application types or deployment stages

Table Gotchas

⚠️

The `state` field updates asynchronously during test execution. Never assume a suite is complete just because you triggered it—always implement polling or use the ATF execution callbacks.

⚠️

Test suite execution creates temporary session state that can interfere with other automated processes. Avoid running multiple large suites simultaneously on the same instance.

The run_type field affects execution behavior—'all' runs every test regardless of individual failures, while 'stop_on_failure' halts the entire suite on first failure
Suite execution timeout is instance-wide and cannot be overridden per suite. Long-running suites may be killed by system limits
The sys_atf_test_suite_test.order field in the junction table controls test execution sequence—missing or duplicate order values cause unpredictable execution order

⚠️

Test suites inherit security context from the executing user. Tests that require elevated permissions may fail when triggered by automated processes running as system accounts.

Deleting a test suite does not automatically clean up related sys_atf_test_result_suite records—implement proper cleanup or results accumulate indefinitely

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 table contains the individual tests that populate suites, connected through the sys_atf_test_suite_test junction table. This many-to-many relationship allows tests to belong to multiple suites and suites to be built from overlapping test collections. The sys_atf_test_result_suite table stores execution results with detailed metrics, timing, and failure analysis.

You'll frequently query sys_user for suite ownership and execution context, and sys_scope when building application-specific test suites. The sysauto_script table commonly references test suites for scheduled execution, while CI/CD integrations often join against sys_app records to trigger application-specific regression testing during deployments.

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	Unique identifier for the test suite. Must be descriptive enough for CI/CD systems to reference programmatically.
description	string	Description	Free-text field for suite purpose and scope. Critical for team collaboration and maintenance documentation.
state	choice	State	Execution state: 'ready', 'running', 'completed'. Updates asynchronously during execution—never assume completion without polling this field.
active	boolean	Active	Controls suite availability for execution. Inactive suites are hidden from UI but remain scriptable via direct API calls.
run_type	choice	Run Type	Execution behavior: 'all' runs every test regardless of failures, 'stop_on_failure' halts suite on first test failure.
application	reference	Application	Reference to sys_scope. Determines application context and scope-based security for test execution.
created_by	reference	Created by	Reference to sys_user. Important for ownership tracking and execution permission inheritance in automated contexts.
abort_on_failure	boolean	Abort on Failure	When true, stops entire suite execution on first test failure. Overrides run_type behavior for critical test suites.
parallel_execution	boolean	Parallel Execution	Enables concurrent test execution within the suite. Can dramatically reduce execution time but may cause resource contention.
copy_of	reference	Copy of	Self-reference to parent suite when cloned. Useful for tracking suite templates and inheritance relationships.
browser_test_only	boolean	Browser Test Only	Restricts suite to browser-based tests only. Server-side tests are skipped when true, affecting execution results.
notes	string	Notes	Internal documentation field. Often used for execution prerequisites, known issues, or maintenance instructions.
sys_package	reference	Package	Reference to sys_package for update set and deployment tracking. Critical for application lifecycle management.
test_count	integer	Test Count	Calculated field showing number of associated tests. Updates when tests are added/removed from suite via junction table.
last_run	glide_date_time	Last Run	Timestamp of most recent suite execution. Used for scheduling logic and freshness validation in CI/CD pipelines.
last_result	choice	Last Result	Result of most recent execution: 'passed', 'failed', 'skipped'. Quick status check without joining to result tables.

Common Queries

Get all active test suites ready for execution

// Most basic query - finds suites available for manual or automated execution
var gr = new GlideRecord('sys_atf_test_suite');
gr.addQuery('active', true);
gr.addQuery('state', 'ready');
gr.orderBy('name');
gr.query();

while (gr.next()) {
    gs.info('Active suite: ' + gr.getValue('name') + 
           ' (' + gr.getValue('test_count') + ' tests)');
}

gs.info('Found ' + gr.getRowCount() + ' executable test suites');

Find failed test suites for a specific application

// Filter by execution state and application scope
// Common pattern for application-specific regression analysis
var gr = new GlideRecord('sys_atf_test_suite');
gr.addQuery('state', 'completed');
gr.addQuery('last_result', 'failed');
gr.addQuery('application.name', 'Human Resources: Core'); // Reference dot-walking
gr.addQuery('active', true);
gr.orderByDesc('last_run');
gr.setLimit(10);
gr.query();

while (gr.next()) {
    gs.info('Failed suite: ' + gr.getDisplayValue('name') + 
           ' - Last run: ' + gr.getDisplayValue('last_run'));
}

Get test suites that haven't run in the last 30 days

// Real-world maintenance query - identifies stale test suites
// Used for cleanup and regression testing gap analysis
var thirtyDaysAgo = new GlideDateTime();
thirtyDaysAgo.addDaysLocalTime(-30);

var gr = new GlideRecord('sys_atf_test_suite');
gr.addQuery('active', true);
gr.addQuery('last_run', '<', thirtyDaysAgo.getDisplayValue());
// Handle suites that have never been executed
gr.addOrCondition('last_run', 'ISEMPTY');
gr.query();

gs.info('Found ' + gr.getRowCount() + ' stale test suites');

Count test suites by application using GlideAggregate

// Aggregate query for reporting and capacity planning
// Shows test coverage distribution across applications
var ga = new GlideAggregate('sys_atf_test_suite');
ga.addQuery('active', true);
ga.addAggregate('COUNT');
ga.groupBy('application');
ga.query();

while (ga.next()) {
    var app = ga.getDisplayValue('application') || 'Global';
    var count = ga.getAggregate('COUNT');
    gs.info('Application: ' + app + ' - Test Suites: ' + count);
}

Wrong vs right way to check suite execution completion

// WRONG: Checking immediately after triggering execution
// The state field updates asynchronously!
var suiteId = 'abc123';
sn_atf.ATF.executeTestSuite(suiteId);
var gr = new GlideRecord('sys_atf_test_suite');
if (gr.get(suiteId) && gr.getValue('state') == 'completed') {
    // This will almost always be false - execution is async!
}

// RIGHT: Poll for completion or use callbacks
var checkCompletion = function(suiteId) {
    var gr = new GlideRecord('sys_atf_test_suite');
    return gr.get(suiteId) && gr.getValue('state') == 'completed';
};

Related Tables

sys_atf_test 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