Working with Helix ALM REST API Part 5: Test Steps Structure

Today we’ll be continuing our series of posts focusing on various features from Perforce’s Helix ALM REST API. Today’s feature is about the structure of test steps for test cases. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface. The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization’s Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization’s workflow, with few limitations. The REST API is available at: https://{API URL}/helix-alm/api/v0/ and the Swagger UI interactive documentation tool is available at: https://{API URL}:{port} where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at: ../Perforce/Helix ALM/helix-alm-rest-api/config/config.json on the machine that is running the Helix ALM instance. Tests Steps Structures The Helix ALM REST API has two different types of test step objects: basic and detailed. Both are quite similar with a few key differences that we will go into depth on in the test case step structure section. Finally, we will look at manual test runs and the structure of the JSON object that the REST API provides. Test Case Step Structure Common Object Structures The general structure of the test case step shares a common base that resembles the following: steps (TestCaseStepContainer object): { self: string stepsData (TestCaseStepData object): { modifiedToCorrectSyntax: boolean type: enum [ basic, detailed ] basic: array of TestCaseBasicStepData objects detailed: array of TestCaseDetailedStepData objects } } Here is where the structure diverges, depending on the type of test case step data object that it is. Before we investigate the basic and detailed test case step data objects, let’s examine a few additional objects that are common to both basic and detailed test case steps. FileReference Object Structure fileReference: { id: int64 referenceType: enum [attachment, sourceFile ] } ExpectedResult Object Structure expectedResult: { text: string fileReferences: array of FileReference objects } SharedStep Object Structure shared: { testCaseID: int64 link: string } Basic First up is the TestCaseBasicStepData object, which represents test cases that have their view mode property set to basic to text. The TestCaseBasicStepData object resembles: { type: enum [comment, step, expected, result, fileReferences, shared ] comment: string expectedResult: ExpectedResult object fileReferences: array of FileReference objects shared: SharedStep object step: TestCaseBasicStep object } Expanding on the TestCaseBasicStep object, we see that it resembles: step: { number: int64 text: string stepRows: array of TestCaseBasicStepRow objects } Drilling down further for the stepRows name and examining the TestCaseBasicStepRow object, we see that it is comprised of: { type: enum [ expectedResult ] expectedResult: ExpectedResult object } Detailed Next is the TestCaseDetailedStepData object, which represents test cases with detailed grid view set on the view mode property. The TestCaseDetailedStepData object resembles: { type: enum [ comment, step, shared ] comment: string shared: SharedStep object step: TestCaseDetailedStep object } Like the basic test case step, the detailed object contains a further object for the test case step. It resembles: step: { number: int64 text: string stepRows: array of TestCaseDetailedStepRow objects } The TestCaseDetailedStepRow is similar to the TestCaseBasicStepRow. It resembles: { type: enum [ expectedResult, stepNote ] expectedResult: ExpectedResult object stepNote: string } Manual Test Run Step Structure Testers can enter results (Pass, Failed, or Undetermined) on each manual test run step in Detailed Grid View, but not in Text View or Grid View. The manual test run step object mostly resembles the same structure as the test case step one but with a few key differences. First, all objects follow the same naming pattern but are renamed to TestRun–. Test runs derived from basic test cases have some additional data that will be explored below. In addition, since there is a lot of overlap with test cases, we will exclude values that were shown in the previous section. TestRunStepsData object: { basic: array of TestRunBasicStepData [ { type: enum [ comment, step, expectedResult, fileReferences,

Mar 14, 2025 - 12:32

Working with Helix ALM REST API Part 5: Test Steps Structure

Today we’ll be continuing our series of posts focusing on various features from Perforce’s Helix ALM REST API. Today’s feature is about the structure of test steps for test cases. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization’s Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization’s workflow, with few limitations.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

Tests Steps Structures

The Helix ALM REST API has two different types of test step objects: basic and detailed. Both are quite similar with a few key differences that we will go into depth on in the test case step structure section. Finally, we will look at manual test runs and the structure of the JSON object that the REST API provides.

Test Case Step Structure

Common Object Structures

The general structure of the test case step shares a common base that resembles the following:

steps (TestCaseStepContainer object):  
{  
  self: string 
  stepsData (TestCaseStepData object):  
  {  
    modifiedToCorrectSyntax: boolean 
    type: enum [ basic, detailed ] 
    basic: array of TestCaseBasicStepData objects 
    detailed: array of TestCaseDetailedStepData objects 
  }  
}

Here is where the structure diverges, depending on the type of test case step data object that it is. Before we investigate the basic and detailed test case step data objects, let’s examine a few additional objects that are common to both basic and detailed test case steps.

FileReference Object Structure

fileReference:
{
  id: int64
  referenceType: enum [attachment, sourceFile ]
}

ExpectedResult Object Structure

expectedResult: 
{ 
  text: string 
  fileReferences: array of FileReference objects 
}

SharedStep Object Structure

shared:  
{ 
  testCaseID: int64 
  link: string 
}

Basic

First up is the TestCaseBasicStepData object, which represents test cases that have their view mode property set to basic to text.

The TestCaseBasicStepData object resembles:

{
  type: enum [comment, step, expected, result, fileReferences, shared ]
  comment: string
  expectedResult: ExpectedResult object
  fileReferences: array of FileReference objects
  shared: SharedStep object
  step: TestCaseBasicStep object
}

Expanding on the TestCaseBasicStep object, we see that it resembles:

step:
{
  number: int64
  text: string
  stepRows: array of TestCaseBasicStepRow objects
}

Drilling down further for the stepRows name and examining the TestCaseBasicStepRow object, we see that it is comprised of:

{
  type: enum [ expectedResult ]
  expectedResult: ExpectedResult object
}

Detailed

Next is the TestCaseDetailedStepData object, which represents test cases with detailed grid view set on the view mode property.

The TestCaseDetailedStepData object resembles:

{
  type: enum [ comment, step, shared ]
  comment: string
  shared: SharedStep object
  step: TestCaseDetailedStep object
}

Like the basic test case step, the detailed object contains a further object for the test case step. It resembles:

step:
{
  number: int64
  text: string
  stepRows: array of TestCaseDetailedStepRow objects
}

The TestCaseDetailedStepRow is similar to the TestCaseBasicStepRow. It resembles:

{
  type: enum [ expectedResult, stepNote ]
  expectedResult: ExpectedResult object
  stepNote: string
}

Manual Test Run Step Structure

Testers can enter results (Pass, Failed, or Undetermined) on each manual test run step in Detailed Grid View, but not in Text View or Grid View.

The manual test run step object mostly resembles the same structure as the test case step one but with a few key differences.

First, all objects follow the same naming pattern but are renamed to TestRun–. Test runs derived from basic test cases have some additional data that will be explored below. In addition, since there is a lot of overlap with test cases, we will exclude values that were shown in the previous section.

TestRunStepsData object:

{
  basic: array of TestRunBasicStepData [
  {
    type: enum [ comment, step, expectedResult, fileReferences, problemStatement ]
    expectedResult: TestRunBasicExpectedResult object
    {
      completed: boolean
      …
    }
    problemStatement: string
    …
  } ]
  detailed: array of TestRunDetailedStepData [
  {
    step: TestRunStep object
    {
      stepRows: array of TestRunStepRow objects [
      {
        type: [ expectedResult, stepNote, testCaseStepNote, problemStatement ]
        problemStatement: string
        testCaseStepNote: string
        …
      } ]
      stepResult: TestRunStepResult object
      {
        dateTime: DateTime
        result: enum [ passed, failed, undetermined ]
        user: User object
      }
      actualResult: ExpectedResult object
      …
    }
  } ]
}

As we can see, there are quite a few differences, but, at the same time, quite a few similarities too. Keep the following in mind when working with manual test runs:

Step results are only returned if they have a value. To add a step result, you must add it to the step and update the manual test run. You cannot delete a step result.
Step notes must be added before expected results.
Step text is read-only and cannot be edited. However, some data can be manipulated depending on the test run type. Consult the table below.

Test Run type	Available editing actions
Text View (basic)	None; read-only.
Grid View (basic)	Change the “completed” property.
	Add, edit, & delete “problemStatement”
Detailed Grid View (detailed)	Add, edit, delete “problemStatement”
	Add, edit, & delete “actualResults”
	Add, edit, & delete “stepNote”[1]
	Add or modify the TestRunStepResult’s “result”

[1] Not to be confused with the “testCaseStepNote”, which is read-only.

Conclusion

In conclusion, the Helix ALM REST API provides a robust and flexible way to interact with test steps in both test cases and manual test runs. By understanding the different object structures for basic and detailed test steps, as well as the nuances between test case steps and manual test run steps, developers can effectively read, write, and manipulate test step data programmatically.

By leveraging the Helix ALM REST API and these test step structures, organizations can build custom tools and integrations to streamline their test management processes. Whether it’s automatically generating test cases, aggregating test results, or synchronizing data with other systems, the possibilities are vast. As always, refer to the official Helix ALM REST API documentation for the most up-to-date and detailed information.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain the error and response codes that you will run into when using the API. In part 6 we will conclude this series by looking at automated testing.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.