Creating reusable custom scripted steps in ATF

[Tom Cullen]

Istanbul brought us the first version of the Automated Testing Framework for ServiceNow.   These out-of-box steps for testing our applications are already saving time and money for all of us.   Forms, UI testing, and server side testing was the Istanbul release focus.   In the Jakarta release, the ATF team is delivering Service Catalog, Rest APIs, Scheduling, Transaction log, and browser options.   The ongoing development of this service is in good hands!

Today I want to go over the steps for creating a custom (and reusable) scripted step for ATF.   Before I begin I'd like to give a shout out to the great work that drjohnchun done with his Automated Test Framework series and the communications from fernando.cremer@servicenow.com, Anson.Mayers, and @Shrity_Verma. I'm always amazed at the depth of the ServiceNow community.

Why use a custom scripted step?

The obvious reason is there is a test scenario that can't be replicated by working with OOB steps only.     That's what happened to me.   I was asked to write a Hacklab for K17.   It was my first experience with ATF.   I took a simple application and tested it manually, then built the corresponding steps as a TEST in ATF and named it "OC1 Application Test 1".   Pretty easy and very straight forward -but- I couldn't exactly replicate my manual test.   The reason was I use workflows whenever possible.   It's the "power of the platform" and saves so much code/test time its crazy.   So when I test, I include the "Show Workflow" related list and once I perform an action, I check to see that the workflow is where I expect it to be.

You guessed it ... there wasn't a Get Workflow OOB step.   The rest of this blog is the way I went about creating one.

Format of a Custom Scripted StepConfig

A custom scripted step is made up of three parts.

1. Header Section
   1. Name of your custom step
   2. Application / Scope
   3. etc.     Pretty standard stuff
2. Script
   1. Description generation script
      1. ** not going to spend any time on this. Simply prints the Step description as documentation for the Test that executes it.
   2. Step execution script
      1. ** going to spend a lot of time on this
3. Variables
   1. Input variables passed into the step
   2. Output variables available for future steps reference

That's it!   Let's build it.   We will concentrate on 2.2 the Step execution script.

Building the Step Execution Script

The first thing I had to do was understand the data.   What table(s) were involved in executing my workflow?   This took a bit of investigative work, but the ServiceNow platform is not a black box.   I ran a test, then navigated to   the Workflow Active Contexts.   I found my workflow, used the handy "right Click" menu and selected "show XML".   From there it was just follow-the-data.

I could manually trace the data and found the current workflow step.   I opened Xplore and wrote a function to replicate what I had just done.   (Sidenote:   If you don't use Xplore yet, go to SHARE and give it a try.   It's awesome.)   Below is a picture of my test function.   The picture may be a bit blurry.   The logic is 1) Read the [wf_context] table using the table name and sys_id, 2) Use the sys_id of the [wf_context] record to read the [wf_executing] table. The data displayed on the right is just what I was looking for.   Now all I need to do is port this code to the (2.2) Step execution script.

Port your script to ATF using the StepConfig template

The hard work is behind us. Navigate to Automated Test Framework > Administration > Step Configurations. Select the Custom Scripted StepConfig record from the list.   We will use this as our template.   Select the COPY ui-action.   Rename the generated "Custom Scripted StepConfig copy"   to any name that makes you happy!   I chose "Custom getWorkflowStep".   Open this record and we'll make our edits.

Make a relevant description for your script.   In my case I used this code

The Step execution script is where it all happens.   It consists of inputs, output, and a setResult.   Looking back at the function we wrote we know the script requires the table-name and sys-id that started the workflow.   Using the Variable section (at the bottom of the form) we'll assign the inputs as Table and Record_ID.   While we're here, we'll also assign our output variables as Workflow_version, Workflow_step_name, and Workflow_step_state.   Notice the generated column names begin with "u_".   Returning to the script code, we make sure that we've received a table and sys_id before we go any further. Set the stepResult accordingly.

Finally, copy/paste the code we tested after our variable verifications.   If we do this right, others will be using our Step, so be polite and add some good comments!

Map the requested information to the outputs object and set an OutputMessage.   Use the UPDATE ui-action and save your custom step configuration.

Test out your new custom getWorkflow step

Now the fun part!   Find an existing Test or create a new Test. At the appropriate time ... use the ADD TEST STEP ui-action.   Select the 'server' type ... scroll down and select your new Custom getWorkflowStep!!   Run your Test(s).   (feel pride)!

My hat is off again to everyone on the community.   I hope this helps someone take the first step to custom steps (what !!).

I will post all code in SHARE and monitor this blog for questions or issues.