Skip to content
Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Automated Test Framework Test API - ServiceNow Fluent

The Automated Test Framework Test API defines automated tests [sys_atf_test] that you can run to confirm that your instance works after making a change.

Note: For the latest ServiceNow Fluent API documentation and examples, see the ServiceNow Fluent API reference and ServiceNow SDK examples repository on GitHub.

For general information about Automated Test Framework tests, see Automated Test Framework (ATF).

Parent Topic:ServiceNow Fluent API reference

Related topics

ServiceNow Fluent

Test object

Create an automated test [sys_atf_test] containing a series of steps to execute.

NameTypeDescription
$idString or NumberRequired. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys\_id. For more information, see ServiceNow Fluent language constructs.Format: `Now.ID['String' or Number]`
nameStringA unique name for the test.
descriptionStringA description of what the test does.
activeBooleanFlag that indicates whether the test is active.Valid values: - true: The test is active. - false: The test isn't active. Default: true
failOnServerErrorBooleanFlag that indicates whether to fail when a server error occurs during the test.Valid values: - true: The test fails when a server error occurs. - false: The test doesn't fail when a server error occurs. Default: true
configurationFunctionFunctionThe steps of the test. Test steps are passed as statements within the atf function. For example:
(atf) => {
    atf.form.openNewForm({
        table: 'sn_example_table',
        formUI: 'standard_ui',
        view: '',
    })
}
For more information about test steps, see Supported test steps.
$metaObject

Metadata for the application metadata.With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.

$meta: {
      installMethod: 'String'
}

Valid values for installMethod:

  • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
  • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.

The output values of test steps with output variables can be saved as variables and used as inputs to other steps using the syntax output.<output-variable>. The output variables can be used both directly as inputs on appropriate fields or inside of a template string, such as with atf.server.log in the following example.

import { Test } from '@servicenow/sdk/core'

Test({
        active: true,
        failOnServerError: true,
        name: 'Simple example',
        description: 'An illustrative test written in fluent',
        $id: Now.ID[1],
    },
    (atf) => {
        atf.form.openNewForm({
            table: 'sn_table_app_reptile_table',
            formUI: 'standard_ui',
            view: '',
        })
        atf.form.setFieldValue({
            table: 'sn_table_app_reptile_table',
            formUI: 'standard_ui',
            fieldValues: {
                reptiles: 'lizard' as any,
            },
        })
        const output = atf.form.submitForm({ assertType: 'form_submitted_to_server', formUI: 'standard_ui' })
        atf.server.recordValidation({
            recordId: output.record_id,
            table: 'sn_table_app_reptile_table',
            assertType: 'record_validated',
            enforceSecurity: true,
            fieldValues: 'reptiles=lizard',
        })
        atf.server.log({
            log: `Submitted record with sys_id: ${output.record_id} to table ${output.table}`
        })
    }
)

Supported test steps

The following test steps are supported. For information about step properties, see the Automated Test Framework (ATF) test step categories documentation.

Note: Some fields available for test steps on forms aren't available as properties in ServiceNow Fluent.

CategorySteps
Application Navigator category- atf.applicationNavigator.applicationMenuVisibility - atf.applicationNavigator.moduleVisibility - atf.applicationNavigator.navigateToModule
Email category- atf.email.generateInboundEmail - atf.email.generateInboundReplyEmail - atf.email.generateRandomString - atf.email.validateOutboundEmail - atf.email.validateOutboundEmailGeneratedByFlow - atf.email.validateOutboundEmailGeneratedByNotification
Form category- atf.form.addAttachmentsToForm - atf.form.clickDeclarativeAction - atf.form.clickModalButton - atf.form.clickUIAction - atf.form.declarativeActionVisibility - atf.form.fieldStateValidation - atf.form.fieldValueValidation - atf.form.openExistingRecord - atf.form.openNewForm - atf.form.setFieldValue - atf.form.submitForm - atf.form.uiActionVisibility
Forms in Service Portal category- atf.form\_SP.addAttachmentsToForm - atf.form\_SP.clickUIAction\_SP - atf.form\_SP.fieldStateValidation\_SP - atf.form\_SP.fieldValueValidation\_SP - atf.form\_SP.openForm\_SP - atf.form\_SP.openServicePortalPage - atf.form\_SP.setFieldValue\_SP - atf.form\_SP.submitForm\_SP - atf.form\_SP.uiActionVisibilityValidation\_SP
Quick start tests for Dashboards- atf.reporting.responsiveDashboard - atf.reporting.responsiveDashboardSharing
REST category- atf.rest.assertJsonResponsePayloadElement - atf.rest.assertResponseHeader - atf.rest.assertResponseJSONPayloadIsValid - atf.rest.assertResponsePayload - atf.rest.assertResponseTime - atf.rest.assertResponseXMLPayloadIsWellFormed - atf.rest.assertStatusCode - atf.rest.assertStatusCodeName - atf.rest.assertXMLResponsePayloadElement - atf.rest.sendRestRequest
Server category- atf.server.addAttachmentsToExistingRecord - atf.server.checkoutShoppingCart - atf.server.createUser - atf.server.impersonate - atf.server.log - atf.server.recordDelete - atf.server.recordInsert - atf.server.recordQuery - atf.server.recordUpdate - atf.server.recordValidation - atf.server.replayRequestItem - atf.server.runServerSideScript - atf.server.searchForCatalogItem - atf.server.setOutputVariables
Service Catalog category- atf.catalog.addItemToShoppingCart - atf.catalog.openCatalogItem - atf.catalog.openRecordProducer - atf.catalog.orderCatalogItem - atf.catalog.setCatalogItemQuantity - atf.catalog.setVariableValue - atf.catalog.submitRecordProducer - atf.catalog.validatePriceAndRecurringPrice - atf.catalog.variableStateValidation - atf.catalog.validateVariableValue
Service Catalog in Service Portal category- atf.catalog\_SP.addItemtoShoppingCart\_SP - atf.catalog\_SP.addOrderGuidetoShoppingCart\_SP - atf.catalog\_SP.addRowToMultiRowVariableSet\_SP - atf.catalog\_SP.navigatewithinOrderGuide\_SP - atf.catalog\_SP.openCatalogItem\_SP - atf.catalog\_SP.openOrderGuide\_SP - atf.catalog\_SP.openRecordProducer\_SP - atf.catalog\_SP.orderCatalogItem\_SP - atf.catalog\_SP.reviewIteminOrderGuide\_SP - atf.catalog\_SP.reviewOrderGuideSummary\_SP - atf.catalog\_SP.saveCurrentRowOfMultiRowVariableSet\_SP - atf.catalog\_SP.setCatalogItemQuantity\_SP - atf.catalog\_SP.setVariableValue\_SP - atf.catalog\_SP.submitOrderGuide\_SP - atf.catalog\_SP.submitRecordProducer\_SP - atf.catalog\_SP.validateOrderGuideItem\_SP - atf.catalog\_SP.validatePriceAndRecurringPrice\_SP - atf.catalog\_SP.variableStateValidation\_SP - atf.catalog\_SP.validateVariableValue\_SP