Autotest API

The Autotest API segment provides access to Autotest functionality, including creating and managing workspaces, exporting/importing collateral and trigger executions.

General Structure

Although not visible in the user interface, Autotest is based on three basic containers.

  • Workspace is a silo containing test plans and collateral like test cases, logins, files etc.
  • Test Plan is a sub-section of a Workspace. A Test Plan can use any collateral from the repository, but not from any other test plan.
  • The Repository consists of any collateral in the workspace that doesn’t belong to any test plan.

Many of the functions supported by Autotest CLI and API require WorkspaceId as a parameter, and optionally also a TestplanId. If you don’t specify TestplanId you are implying that the operation should run in the repository.


The Autotest API consists of a number of collections. The workspaces collection is the root collection that provides access to the other collections.

workspacesA collection of workspaces. Listing this collection provides a list of workspaces with complete configuration details. Indexing into this collection by database ID (workspaces/{WorkspaceId}) returns details for the specified workspace, and provides further access to the other collections.
testplanTestplan is a sub-collection of workspaces (workspaces/{WorkspaceId}/testplan) and provides read access to test plan nodes as well as IPC endpoints for importing/exporting and execution.

Note that only concrete test plan nodes are accessible. Virtual nodes (as reached through a test case reference) are not accessible.
variablesVariables is a sib-collection of workspaces (workspaces/{WorkspaceId}/variables) and provides read and update support for variable definitions.
loginsLogins is a sub-collection of workspaces (workspaces/{WorkspaceId}/logins) and provides read/update support for logins.


Access to the Autotest API is authorized by the static permission Automation/Tools/Enabled in OmniFi Admin. Users that can use Autotest in desktop mode can use the Autotest API, if enabled.


Curl usage examples are included in the documentation web page and completed with PowerShell examples as needed. This section provides a few samples of various usage scenarios.

Listing Workspaces

A list of workspaces can be retrieved by listing the workspaces root collection using curl:

curl -L -X GET "http://localhost/api/autotest/workspaces" ^
    -H "Accept: application/json" ^
    -H "Authorization: Basic dXNlcjpwYXNzd29yZA=="

Executing a test plan node

You can execute the whole or a part of the test plan by calling the execute IPC endpoint on the testplan collection:

curl -L -X POST "http://localhost/api/autotest/workspaces/7/testplan/execute?Path=Repository/My%20Task&TestplanId=2" ^
    -H "Accept: application/json" ^
    -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" ^
    -H "Content-Length: 0"

Note that the node to execute can be referenced using the Path and TestplanId query arguments, or as a specific node ID:

curl -L -X POST "http://localhost/api/autotest/workspaces/7/testplan/-62180/execute" ^
    -H "Accept: application/json" ^
    -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" ^
    -H "Content-Length: 0"

Paths are not strictly unique in the Autotest test plan. Unlike a file system, two sibling nodes in Autotest can have the same name which makes a path referencing through either of them ambiguous. In such cases Autotest API will respond with an error code, and you need to use the later form of the request, using ID.

In addition, is you specify Path but not TestplanId, Path is expected to exist in the repository rather than any specific testplan.

Creating a new repository

Creating a new repository is as easy as supplying a unique name and storage location, but if you need to configure result reporting, concurrency and stop conditions the request body becomes fairly complex.

As an alternative you can duplicate an existing workspace. This requires multiple API calls and is best performed using PowerShell or any other scripting language. PowerShell has the advantage of having native REST API integration alongside automatic conversion to and from Json.

# This example extracts the definition of a template repository, modifies
# it with a new Name and StorageLocation and imports it as a new workspace.
# The result reporting extension password is re-set since the extract excludes
# the password.

# Define the serivice user/pass
$suser = "user"
$spass = "password"
$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $suser, $spass)))

# Define the name of the repository and create a storage location as a derivative.
$name = "New Workspace"
$path = ("C:/test/{0}" -f $name)

# Define the result reporting extension password.
$pass = "extension_password"

# Define the request header. This will be used for both calls.
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Accept", "application/json")
$headers.Add("Authorization", "Basic $auth")
$headers.Add("Content-Type", "application/json")

# Read the template workspace and reconfigure
$workspaces = Invoke-RestMethod "http://localhost/api/autotest/workspaces?Name=Template Workspace" -Method 'GET' -Headers $headers
$workspace = $workspaces[0]

$workspace.Name = $name
$workspace.StorageLocation = $path
$workspace.ResultReportingPassword = $pass
$body = $workspace | ConvertTo-Json

$response = Invoke-RestMethod "http://localhost/api/autotest/workspaces" -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json