Automated Test Framework (ATF): custom Step Configuration

August 13, 2019 6:37 am

Published by

Automated Test Framework: custom Step Configuration

Step Configurations allow you to create custom test steps above and beyond what is included with ServiceNow. Step Configurations are server-side meaning you have the full power of server-side scripting at your disposal.

We’ll create a Step Configuration that checks if the ‘Incident opened on my behalf’ Notification has been correctly sent after a self-service user has opened an incident. Our test case might be something like this:

When a new Incident is created, the ‘Incident opened on my behalf’ Notification should be sent to the user who opened the Incident

Create a new Test

ATF Tests should be small and specific to your stories/test cases so we’ll create a new Test for the test case we defined above. To save us some time and work, we can copy an existing demo/example test to use as a template.

  1. Go to Automated Test Framework > Tests
  2. Open INCIDENT MGMT: Incident creation – Self service
    Note: these demo data tests are read only examples only but we can use them as a template for our own tests
  3. Click the Copy Test UI Action
  4. Complete the form
    • Name: Incident Creation – Self service: notification
    • Description: Check for notification on creation of incident
  5. Save

Our custom Step Configuration will need to know the sys_id of the record that gets inserted when the the Record Producer is submitted. This sys_id will be available in an Output Variable on the Submit Record Producer Test Step – take a look at it now:

  1. Scroll down to the Test Steps related list and open Test Step: Submit Record Producer
  2. Click the info icon next to the Step Config field to open the baseline Submit record producer Step Configuration
  3. Scroll down to the Output Variables related list
  4. Note the Type of the record_id Output variable

Create a new Step Configuration

We now need to create a new Step Configuration that will check for our notification

  1. Go to Automated Test Framework > Step Configurations > New
  2. Complete the form
    • Name: INCIDENT: Check opened notification
    • Category: Server
    • Order: 1000
    • Template reminder: INCIDENT: Check opened notification
    • HTML Description: INCIDENT: Check opened notification
  3. Save

Before we write the script that will actually check for the notification we need to define an input variable so our script will have access to the sys_id of the record that was created earlier in the test

  1. Scroll down to Input Variable related list > New
  2. Click on the Advanced view UI action
  3. Complete the form
    • Type: Document ID (this should match the Type of the Output Variable we checked earlier)
    • Label: Document ID
    • Column name (autofills): u_record_id
    • Attributes: element_mapping_provider=com.glide.automated_testing_framework.ATFVariableElementMapper
  4. Submit

The Attribute we added allows us to map the value of an Output Variable into our Input Variable.

Now we can write the script that will actually check for the notification. Take a moment to review the comment in the Step execution script field, it contains some example of how to use the default attributes that are passed to the script. Add the following script and Save:

(function executeStep(inputs, outputs, stepResult, timeout) {
  //get the value passed into the Record ID input variable
  var inc = inputs.u_record_id;

  //sys_id of the Notification we are checking for 
  var created_notification = '8f9389b5c0a8016401715c208ff9bf48';

  //wait ~30 seconds to ensure that the email has enough time to be generated
  var seconds = parseInt(30) * 1000;
  var start = parseInt(new Date().getTime()) + seconds;
  while(start>parseInt(new Date().getTime())){
    // do nothing

  //get all emails associated with the record that was inserted
  var incEmails = new GlideRecord('sys_email');
  incEmails.addQuery('instance', inc);

    //if an email log record exists that matches the email on the ticket and the 
    //specified notification, the email was sent correctly 
    var emailId = incEmails.getUniqueValue();
    var grEmailLog = new GlideRecord('sys_email_log');
    grEmailLog.addQuery('email', emailId);
    grEmailLog.addQuery('notification', created_notification);
      //output message that will appear in test results
      stepResult.setOutputMessage('TEST STEP: email was sent');
      //the result of this Test Step will be successfull, any subsequent steps
      //in the Test will be processed


  stepResult.setOutputMessage('TEST STEP: email was NOT sent');
  //the result of this Test Step will be failure, the Test will halt and fail

}(inputs, outputs, stepResult, timeout));

Create a new Test Step

  1. Go to Automated Test Framework > Tests > open the Test created earlier
  2. Scroll down to Test Steps related list
  3. Select all Test Steps from Execution order 5 and onwards – delete or inactivate these Test Steps
  4. Click Add Test Step
  5. Select the Server category > INCIDENT: Check opened notification
  6. Insert after: 4 – Submit Record Producer
  7. Click Next

This creates a new Test Step in our Test based on our custom Step Configuration.

Important: We must pass the sys_id of the created record from the Output Variable of Step 4 into the Record ID Input Variable of Step 5

  1. Click the Element Mapping icon  next to the Record ID field at the bottom of the form
  2. Select Step 4 Submit Record Producer
  3. Select Record ID
  4. Submit

Test your Test

  1. Go to Automated Test Framework > Tests > open your Test record
  2. Click the Run Test UI action in your Test record. This will open a new Client Test Runner in a new browser tab that will run your Test. Observe the Record producer opening and submitting.
  3. Go back to tab with your Test Record open and you will see the progress of your test execution
  4. The final bar (independent steps with order 5-5) should show green and the Test will complete successfully!

We must also check that the test will correctly fail if the notification is NOT sent

  1. Go to System Notification > Notifications > Open Notification: Incident opened for me
  2. Set active: false and Save
  3. Repeat the steps above to run the Test again – this time the final bar should show red and the test should fail as the Notification was not sent
  4. Click on Go to results to see why the test failed, you should see the ’email NOT sent’ message we specified in the script of our Test Configuration

Congratulations, you have created, used and tested a custom Step Configuration!

Training and Certification

If you’re not already familiar with the Automated Test Framework then it’s time to get up to speed! Implementing ATF as part of your development process is crucial to making sure platform upgrades go quickly and smoothly.