ATF Testing Guide

This guide covers the 9 Automated Test Framework (ATF) tools available when ATF_ENABLED=true. Use these tools to run test suites, analyze failures, and automate regression testing in ServiceNow.

Prerequisites

ATF_ENABLED=true
WRITE_ENABLED=true  # Required for running tests (write operations)

Tool Overview

Common Workflows

Run Regression Suite After Deployment

# 1. List available test suites
list_atf_suites

# 2. Run the regression suite
run_atf_suite sys_id="<suite_sys_id>"
# Returns: {result_sys_id: "abc123", status: "running"}

# 3. Get results
get_atf_suite_result result_sys_id="abc123"
# Returns: {status: "complete", passed: 47, failed: 2}

# 4. Investigate failures (ATF Failure Insight)
get_atf_failure_insight result_sys_id="abc123"
# Returns: changes between last pass and this failure

ATF Failure Insight

get_atf_failure_insight is a latest release tool that compares metadata between the last successful ATF run and the current failed run. It surfaces:

• User role changes (a role was added/removed from the ATF user)
• Field value changes on records referenced by tests
• Configuration changes that may have broken test assertions

Example Output

{
  "changes_since_last_pass": [
    {
      "type": "role_change",
      "user": "atf_test_user",
      "removed_role": "itil",
      "changed_at": "2025-03-15T10:23:00Z"
    },
    {
      "type": "field_change",
      "table": "sys_properties",
      "field": "glide.authenticate.multifactor",
      "old_value": "false",
      "new_value": "true"
    }
  ]
}

API: GET /api/now/table/sys_atf_failure_insight

ServiceNow ATF APIs

build-atf-suite Capability Prompt

New in v4.0.0. The build-atf-suite capability prompt provides a guided 7-step workflow for generating complete ATF test suites from natural language descriptions. It works with your AI assistant to scaffold tests, configure assertions, and set up test data.

How It Works

Invoke the capability by asking your AI assistant to "build an ATF suite" or referencing the prompt directly. The workflow walks through these steps:

1. Scope definition -- identify the table, process, or feature under test
2. Coverage level selection -- choose basic, standard, or comprehensive coverage
3. Test case generation -- AI generates test cases based on scope and coverage
4. Test data setup -- define required test data records and prerequisites
5. Assertion configuration -- specify expected outcomes for each test step
6. Suite assembly -- group tests into an ATF suite with proper ordering
7. Review and deploy -- validate the suite and create it on the instance

Coverage Levels

Example

# Ask your AI assistant:
Build an ATF suite for the incident management process with standard coverage

# The assistant will walk through each step, asking for input
# and generating tests along the way. At the end, the suite
# is created on your instance via run_atf_suite / create tools.

Configuration Example

ATF_ENABLED=true
WRITE_ENABLED=true
MCP_TOOL_PACKAGE=platform_developer