Autotest command-line

Autotest comes with a command-line tool autotest-cli.exe that allows certain tasks to be scripted. The command line tool provides the same abilities as Autotest API, including creating and managing repositories and test plans, exporting/importing test plan collateral and triggering executions. The benefit with Autotest CLI is that it does not require OmniFi Access to be installed and it isn’t bound to a specific OmniFi database the way OmniFi Access is.

This makes it ideal to use in ad-hoc scenarios where for example you would like to start up a large execution after the nightly maintenance window, or if you during a project would like to run a test package every night to Saturday after the gold environment has been copied. Using autotest-cli.exe and for example the Windows scheduler you can automate such scenarios.

Command-line tools such as autotest-cli can also easily be invoked from e.g. yaml, so if you need to include automated testing for your docker images autotest-cli provides a convenient way to import, configure and execute your test package

📘

For production scenarios we still suggest using OmniFi Access and Autotest API since the service and event logs provide a level of auditability that autotest-cli does not.

Usage

The basic usage pattern of autotest-cli is:

autotest-cli.exe -U <user> -P <password> -S <system> -F <function> [<function arguments>]

To get a complete listing of all supported functions, run:

autotest-cli.exe -H

To get help with a specific function, run:

autotest-cli.exe -H <function> e,g. autotest-cli.exe -H Execute

📘

Individual arguments starting with a ‘-‘ character are considered argument name. To input an argument value starting with a ‘-‘ character, escape it with a ‘\’, e.g.

-Offset \-2

If the argument value starts with the sequence “-“, prepend the escape character, e.g.
-Argument \\-value

WorkspaceId and TestPlanId

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.

Reading arguments from STDIN

Any one argument to autotest-cli can be read from STDIN by substituting the argument value with the ‘@’ character, e.g:

echo fk | autotest-cli.exe -U @

This will read the username fk from STDIN rather than the argument list. This is mostly useful where larger models need to be supplied, such as when creating a workspace:

type workspace.json | autotest-cli.exe -U fk … -F CreateWorkspace -WorkspaceModel @

Examples

Reading workspace configuration

If you know the database ID of the workspace you can use the ReadWorkspace function to read that specific workspace.

Since workspace names are not unique in Autotest, most autotest-cli functions require a workspace ID argument. If you only know the workspace name you can instead use the ListWorkspaces function and filter on Name.

autotest-cli.exe -F ListWorkspaces ^
    -U <user_name> ^
    -P <password> `
    -S <system_name> ^
    -Name <workspace_name>

The output is in Json format. For better readability you can use the -O flag:

autotest-cli.exe -F ListWorkspaces ^
    -U <user_name> ^
    -P <password> `
    -S <system_name> ^
    -Name <workspace_name> ^
    -O JsonIndented

Importing testcases

You can import testcases and other collateral that has been exported from one workspace into another workspace.
Firstly, we need to make sure there is a group to import into using the CreatePath function:

autotest-cli.exe -F CreatePath ^
    -U <user_name> ^
    -P <password> ^
    -S <system_name> ^
    -WorkspaceId <workspace_id> ^
    -TestplanId <testplan_id> ^
    -Path Imports

This will create a new root group “Imports” that we can import into.
To import an archive, we use the Import function:

autotest-cli.exe -F Import ^
    -U <user_name> ^
    -P <password> ^
    -S <system_name> ^
    -WorkspaceId <workspace_id> ^
    -TestplanId <testplan_id> ^
    -Path Imports ^
    -SourceFile <path_to_archive>

The Import function accepts a few additional arguments that are omitted in this example, pertaining to how archive collateral should be mapped to existing collateral already in the workspace. If we import into a new workspace we can leave these settings unspecified.

Executing

To start executions in Autotest we can use the Execute function and specify what portion to execute using the Path argument:

autotest-cli.exe -F Import ^
    -U <user_name> ^
    -P <password> ^
    -S <system_name> ^
    -WorkspaceId <workspace_id> ^
    -TestplanId <testplan_id> ^
    -Path Imports

PowerShell example

Though autotest-cli can use useful on its own, invoking it from a script language enables a range of new usage scenarios. PowerShell is a powerful, Windows-native scripting language that can interpret the Json data structures returned and accepted by autotest-cli.

This example shows a more complex script that extracts workspace configuration from a template, reconfigures it and crates a new workspace, exports collateral and imports it into the new workspace and finally executes it.

# Define the service user/pass
$suser = "<user_name>"
$spass = "<password>"

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


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

# Get the template workspace definition from an existing workspace
"Fetching template workspace ..."
$workspaces = ./autotest-cli.exe -F ListWorkspaces `
    -U $suser `
    -P $spass `
    -S PROD `
    -Name Test `
    | ConvertFrom-Json
$workspace = $workspaces[0]

$template_ws_id = $workspace.Id

# Update the name and storage location
# Also update the result reporting extension password, as this isn't exported
$workspace.Name = $name
$workspace.StorageLocation = $path
$workspace.ResultReportingPassword = $pass

"Creating new workspace ..."
$body = $workspace | ConvertTo-Json
$response = ($body | ./autotest-cli.exe -U $suser -P $spass -S PROD -F CreateWorkspace -WorkspaceModel "@")

# Check for success
if ($LASTEXITCODE -ne "0") {
    ("Failed to create workspace: {0}" -f $response)
    exit $LASTEXITCODE
}

$workspace = ($response |ConvertFrom-Json)
$new_ws_id = $workspace.Id
"Created workspace {0} - {1}" -f $new_ws_id, $workspace.Name

# Addan Imports group
$hide = ./autotest-cli.exe -F CreatePath `
    -U $suser `
    -P $spass `
    -S PROD `
    -WorkspaceId $new_ws_id `
    -Path Imports

"Exporting collateral from template ..."
$exportfile = Join-Path -Path $env:TEMP -ChildPath "export.zip"
./autotest-cli.exe -F Export `
    -U $suser `
    -P $spass `
    -S PROD `
    -WorkspaceId $template_ws_id `
    -Path "Repository/Deal entry" `
    -IncludePassword True `
    -DestinationFile $exportfile

# Check that file was created
if (!(Test-Path $exportfile)) {
    "Exported file '{0}' doesn't exist!" -f $exportfile
    exit 1 
}

"Importing collateral to new workspace ..."
./autotest-cli.exe -F Import `
    -U $suser `
    -P $spass `
    -S PROD `
    -WorkspaceId $new_ws_id `
    -Path Imports `
    -SourceFile $exportfile

"Deleting export file ..."
Remove-Item $exportfile

"Executing ..."
./autotest-cli.exe -F Execute `
    -U $suser `
    -P $spass `
    -S PROD `
    -WorkspaceId $new_ws_id `
    -Path "Imports/Deal entry" `
    | ConvertFrom-Json