ATF: Setting Up a Custom Step Configuration to Query a Manager

ServiceNow’s Automated Testing Framework (ATF) application is a powerful tool with much to offer to users looking to create automated tests. We often find ourselves taking the same steps across several tests that would not necessarily warrant the use of a template.

For example, there are many instances where a manager’s approval or action is required. In this situation, we could select a Run Query step configuration and build a query on the sys_user table. Each role and condition is added, and we ultimately end up with a user record.

The limitation here is only having access to the document_id of the record returned from your query. We are unable to view any of the returned user’s data unless we impersonate the user or take additional steps to get the user’s data. This can be slightly inconvenient if all that is needed is the manager’s email.

Whether you find that you are creating the same Run Query step or would like a faster way to get the user data you need, a custom step configuration might be the best option for you and your team.

Creating A New Step Configuration

Step configurations can be created from the Automated Test Framework (ATF) application by clicking on the Step Configurations module and then clicking the New button at the top right-hand side of the page.

For this example, we have named our Step Configuration “Query Manager.”

Our Step Environment will be set to Server – Independent, and the Category can be set to any category you would like for your step to be shown under. In this case, we have chosen ‘server’.

The Template Reminder field is a reminder message when the step is created through a template, and the HTML description is the text that will be displayed when the test step is selected during the creation of a test.

Description generation script

The Description generation script is what you will see as the step description when the step has been added to your test case.

For now, we will use the code below to output a simple message explaining the test step:

(function generateDescription(step) {

    var description = gs.getMessage("Query for an active manager that does not have the admin role");    
    return description;    


The output of the code will be as shown below:

Input/Output Variables

Since we don’t require any input from the user on this step configuration, there is no need to set Input Variables. However, we will need to create an output variable that will allow users to access the returned user data in subsequent tests.

To create an output variable, click on the New button on the right-hand side of the Output Variables section below Related Links.

On the Output Variables form, we will set the Type to Reference since we will be referencing the sys_user table. In this example, we set the Label to User, but it can be set to a name that makes sense for your step.

The Column name will automatically populate based on your entry for Label.

Right-click in the form header and click Save to save your changes.

Next, we will set the fields in the Reference Specification section. This section is mandatory since we have selected Reference as the Type of output.

Reference should be set to User (sys_user), and no additional information needs to be added.

Make sure the checkbox at the top of the form is set to active, and click Update to save your changes and return to the Test Step Config form.

Step Execution Script

Now we are ready to create the step execution script that will run the query and output the user information.

// We only need outputs and StepResult as these are the only two things we are passing
(function(outputs,stepResult) {
    //Set variable to define the manager and specify the table name to be queried
    var testManager = new GlideRecord('sys_user');

    // Set the query parameters
    testManager.addQuery('active','=', true);

    // Run the query

    // If there is an existing record returned, move on to an additional script. If there isn't, fail with a message.
    if ( {
        // Getting the count of total records so we can pick a random user
        var numRecs = testManager.getRowCount();
        var randomRecord = Math.floor(Math.random()*numRecs);
        // grab the random user based on the equation above
        // grab the sys_id of the user so we can output it for future test steps
        var manager = testManager.sys_id;
        // the outputs variable should always match what you set up in the step configuration. u_user was what we used in the initial setup of the variable and what should be used to pass the manager record
        outputs.u_user = manager;
        // Success message that also shows the user the selected manager and the count of records returned
        stepResult.setOutputMessage("Found user: " + outputs.u_user.getDisplayValue() + '\nNumber of records: ' + numRecs);
    } else {
           // No manager was found, output what is being returned to the user so further investigation of the failure can be done
               stepResult.setOutputMessage("Failed to find manager: " + manager);


If you would like to add to the query to make it more specific to your needs, you can do so by simply adding another .addQuery line: 


    // Set the query parameters
    testManager.addQuery('active','=', true);

    // Add additional lines if needed. Any column in the sys_user table can be queried to match your requirements
    testManager.addQuery('name','!=','John Doe');

    // Run the query


You can also easily edit the query to simply find an active user with additional parameters if that’s what fits your team’s needs. 

    // The query will return all active users that do not have the admin role and are not named John Doe
    testManager.addQuery('active','=', true);
    testManager.addQuery('name','!=','John Doe');

    // Run the query


It is recommended to name your variables appropriately. If you alter the code to return active users instead of managers, you can update the testManager variable to be testUser or something more fitting for the actual query. 

Once you have the step execution script set, save your changes, and your step configuration is ready to use. 


Adding the Step to a Test Case

Using the new step configuration is as simple as adding a step to your test case. Open the test case you will be using the Query Manager step on. Click on Add Test Step to open the step modal. 

You should see your new step configuration under the Server category under Query Manager. You will also see the description set during the setup and can now add it as a step in your test case. Click Next to add it to your test. 

Next, click Add Test Step and add the Impersonate step. When configuring the Impersonate step, you should be able to add the user returned from the previous step.

All user information is available for use by using a single step configuration, saving time and energy.

Final Thoughts

Creating custom step configurations such as Query Manager allows users to have a centralized place to update queries if the same query is being used across multiple tests. They also cut down on time spent creating test cases since a single step can provide the user data needed to fill out form fields, impersonate, and find additional users, etc.