atf-testing

name	atf-testing
description	Build ServiceNow Automated Test Framework tests and suites — impersonation, form steps, assertions, server-side script steps, test parameters, and execution via snow_create_atf_test / snow_execute_atf_test.
license	Apache-2.0
compatibility	Designed for Snow-Code and ServiceNow development
metadata	{"author":"serac","version":"1.0.0","category":"servicenow"}
tools	["snow_create_atf_test","snow_execute_atf_test","snow_query_table","snow_artifact_manage"]

Automated Test Framework (ATF) for ServiceNow

ATF provides automated testing capabilities for ServiceNow applications, enabling regression testing and continuous integration.

ATF Architecture

Test Hierarchy

Test Suite: Incident Management Tests
├── Test: Create Incident
│   ├── Step 1: Impersonate User
│   ├── Step 2: Open New Record
│   ├── Step 3: Set Field Values
│   ├── Step 4: Submit Form
│   └── Step 5: Assert Values
├── Test: Assign Incident
│   └── Steps...
└── Test: Resolve Incident
    └── Steps...

Key Tables

Table	Purpose
sys_atf_test	Test definitions
sys_atf_step	Individual test steps
sys_atf_test_suite	Test suite groupings
sys_atf_test_suite_test	Suite-test relationships
sys_atf_test_result	Test execution results

Test Step Types

Common Step Types

Step Type	Purpose	Example
Impersonate	Run as specific user	Test as ITIL user
Open a New Form	Create new record	New incident form
Open an Existing Form	Edit record	Open INC0010001
Set Field Values	Populate fields	Set priority, description
Click a UI Action	Trigger button	Click "Save"
Assert Field Values	Validate values	Priority = 1
Run Server Side Script	Execute script	Custom validation
Wait	Pause execution	Wait for async

Creating Tests

Basic Test Structure (ES5)

// Create a new ATF test
var test = new GlideRecord("sys_atf_test")
test.initialize()
test.setValue("name", "Test: Create High Priority Incident")
test.setValue("description", "Verify high priority incident creation workflow")
test.setValue("active", true)
test.setValue("application", "global") // or scoped app sys_id
var testSysId = test.insert()

// Add test steps
function addTestStep(testId, order, stepType, config) {
  var step = new GlideRecord("sys_atf_step")
  step.initialize()
  step.setValue("test", testId)
  step.setValue("order", order)
  step.setValue("step_config", stepType)

  // Set step-specific configuration
  for (var key in config) {
    if (config.hasOwnProperty(key)) {
      step.setValue(key, config[key])
    }
  }

  return step.insert()
}

Impersonate Step

// Step 1: Impersonate ITIL user
addTestStep(testSysId, 100, "sys_atf_step_config_impersonate", {
  description: "Impersonate ITIL user",
  inputs: JSON.stringify({
    user: "itil", // or sys_id
  }),
})

Open New Form Step

// Step 2: Open new incident form
addTestStep(testSysId, 200, "sys_atf_step_config_open_new_form", {
  description: "Open new incident form",
  inputs: JSON.stringify({
    table: "incident",
  }),
})

Set Field Values Step

// Step 3: Set field values
addTestStep(testSysId, 300, "sys_atf_step_config_set_field_values", {
  description: "Set incident fields",
  inputs: JSON.stringify({
    table: "incident",
    values: [
      { field: "short_description", value: "ATF Test Incident" },
      { field: "priority", value: "1" },
      { field: "category", value: "network" },
      { field: "caller_id", value: "admin" },
    ],
  }),
})

Submit Form Step

// Step 4: Submit form (click Save)
addTestStep(testSysId, 400, "sys_atf_step_config_click_ui_action", {
  description: "Save the incident",
  inputs: JSON.stringify({
    ui_action: "sysverb_insert", // Submit/Insert action
  }),
})

Assert Field Values Step

// Step 5: Assert values
addTestStep(testSysId, 500, "sys_atf_step_config_assert_field_values", {
  description: "Verify incident was created correctly",
  inputs: JSON.stringify({
    table: "incident",
    assertions: [
      {
        field: "priority",
        operator: "equals",
        value: "1",
      },
      {
        field: "state",
        operator: "equals",
        value: "1", // New
      },
      {
        field: "number",
        operator: "is not empty",
      },
    ],
  }),
})

Server-Side Script Steps

Custom Validation Script (ES5)

// Step: Run Server Side Script
// Script (ES5 only!):

;(function (outputs, steps, params, stepResult) {
  // Access outputs from previous steps
  var incidentSysId = steps["step_sys_id"].record_id

  // Perform custom validation
  var gr = new GlideRecord("incident")
  if (gr.get(incidentSysId)) {
    // Check business rule fired
    if (gr.getValue("assignment_group") === "") {
      stepResult.setOutputMessage("Assignment group not set by business rule")
      stepResult.setFailed()
      return
    }

    // Check SLA attached
    var sla = new GlideRecord("task_sla")
    sla.addQuery("task", incidentSysId)
    sla.query()

    if (!sla.hasNext()) {
      stepResult.setOutputMessage("No SLA attached to incident")
      stepResult.setFailed()
      return
    }

    // All validations passed
    outputs.incident_number = gr.getValue("number")
    outputs.sla_count = sla.getRowCount()
    stepResult.setOutputMessage("All validations passed")
  } else {
    stepResult.setOutputMessage("Incident not found")
    stepResult.setFailed()
  }
})(outputs, steps, params, stepResult)

Data Setup Script (ES5)

// Step: Setup test data
;(function (outputs, steps, params, stepResult) {
  // Create test user if needed
  var user = new GlideRecord("sys_user")
  user.addQuery("user_name", "atf_test_user")
  user.query()

  if (!user.next()) {
    user.initialize()
    user.setValue("user_name", "atf_test_user")
    user.setValue("first_name", "ATF")
    user.setValue("last_name", "Test User")
    user.setValue("email", "[e-mail]")
    user.setValue("active", true)
    outputs.user_sys_id = user.insert()
  } else {
    outputs.user_sys_id = user.getUniqueValue()
  }

  stepResult.setOutputMessage("Test user ready: " + outputs.user_sys_id)
})(outputs, steps, params, stepResult)

Cleanup Script (ES5)

// Step: Cleanup test data (always runs)
;(function (outputs, steps, params, stepResult) {
  var testRecordId = steps["create_incident_step"].record_id

  if (testRecordId) {
    var gr = new GlideRecord("incident")
    if (gr.get(testRecordId)) {
      gr.deleteRecord()
      stepResult.setOutputMessage("Cleaned up test incident: " + testRecordId)
    }
  }
})(outputs, steps, params, stepResult)

Test Suites

Creating Test Suite

// Create test suite
var suite = new GlideRecord("sys_atf_test_suite")
suite.initialize()
suite.setValue("name", "Incident Management Regression Suite")
suite.setValue("description", "Full regression tests for incident management")
suite.setValue("active", true)
var suiteSysId = suite.insert()

// Add tests to suite
function addTestToSuite(suiteId, testId, order) {
  var link = new GlideRecord("sys_atf_test_suite_test")
  link.initialize()
  link.setValue("test_suite", suiteId)
  link.setValue("test", testId)
  link.setValue("order", order)
  return link.insert()
}

addTestToSuite(suiteSysId, createTestId, 100)
addTestToSuite(suiteSysId, assignTestId, 200)
addTestToSuite(suiteSysId, resolveTestId, 300)

Parameterized Tests

Using Test Parameters

// Test with parameters
var test = new GlideRecord('sys_atf_test');
test.initialize();
test.setValue('name', 'Test: Create Incident with Priority');
test.setValue('parameters', JSON.stringify({
    priority: '2',
    category: 'software'
}));
test.insert();

// In step, reference parameter
{
    "values": [
        { "field": "priority", "value": "${priority}" },
        { "field": "category", "value": "${category}" }
    ]
}

MCP Tool Integration

Available ATF Tools

Tool	Purpose
snow_create_atf_test	Create test
snow_create_atf_test_step	Add step to test
snow_create_atf_test_suite	Create suite
snow_execute_atf_test	Run test
snow_get_atf_results	Get results
snow_discover_atf_tests	Find existing tests

Example Workflow

// 1. Create test
var testId = await snow_create_atf_test({
  name: "Test: Incident Priority Escalation",
  description: "Verify priority changes trigger notifications",
})

// 2. Add steps
await snow_create_atf_test_step({
  test_id: testId,
  order: 100,
  type: "impersonate",
  user: "itil",
})

await snow_create_atf_test_step({
  test_id: testId,
  order: 200,
  type: "server_script",
  script: createIncidentScript,
})

// 3. Execute test
var resultId = await snow_execute_atf_test({
  test_id: testId,
})

// 4. Get results
var results = await snow_get_atf_results({
  result_id: resultId,
})

Best Practices

1. Isolate Test Data - Create and cleanup test data in each test
2. Use Impersonation - Test as actual user roles
3. Atomic Tests - Each test validates one scenario
4. Descriptive Names - Clear test and step descriptions
5. Order Steps - Use 100, 200, 300 for easy insertion
6. Handle Async - Add wait steps for async operations
7. Cleanup Always - Use finally steps for cleanup
8. Parameterize - Use parameters for reusable tests

Common Assertions

Assertion	Use Case
equals	Exact value match
not equals	Value exclusion
is empty	Field should be empty
is not empty	Field must have value
contains	Substring match
starts with	Prefix match
greater than	Numeric comparison
less than	Numeric comparison