The Step CLI (Command Line Interface) is used for all operations with Step. It provides an integration with the Step server and an easy way to integrate Step with a CI/CD pipeline. Currently it is limited to the operations related to Automation Packages but might be extended in the future. For Java specific projects, the CLI is also available as a Maven plugin.

The Step CLI supports following operations for Automation Packages:

Execute Automation Packages locally
Execute Automation Packages within Step in isolation
Deploy the content of Automation Packages to Step and enable the contained schedules
Deploy an Automation Package Library to Step

Note: these operations support both local packages and automation packages stored on a maven artifact repositories

Get the CLI

Starting with Step 26, the CLI can be downloaded from following locations, depending on the edition of Step used:

Step Open Source: GitHub release page
Step Enterprise: Enterprise download section

Requirements:

Use the same CLI version as the Step server you want to operate
Make sure to have Java installed (at least a JRE version 11+)

CLI usage

Simply execute the CLI in a terminal without any options to get the most current and detailed documentation. You can get contextual help for each of the available operations.

$ step
Applying properties from /home/stepd/stepcli.properties...
Usage: step [-hV] [COMMAND]
The CLI interface to communicate with Step server
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help  Display help information about the specified command.
  ap    The CLI interface to manage automation packages in Step

Example to get detailed help for the deploy operation:

$ step ap deploy --help

The following sections on this page contain a non-exhaustive list of the available commands and options with examples.

Automation Package location

The CLI can work directly with a folder containing your Automation Package content or with a package (Zip or Jar file). With no option, the CLI considers the current folder as the root of your Automation Package.

Remember that at a minimum, an Automation Package must contain an automation-package.yaml file at its root. The only exception being for Java Automation Packages which may declare entities using annotations.

Example to define the location of the package

step ap execute --local  -p /mnt/c/step-samples/automation-packages/load-testing-jmeter/

Excluding Files from Automation Packages

If you use the CLI to deploy or execute (remotely) the automation package as folder, you can ignore some files during the packaging phase. These files won’t be sent and stored on the Step server. To do this you only need to add the .apignore file to the root folder of your automation package. The .apignore file supports the same syntax as the .gitignore for Git repositories.

Example to ignore a file ignoredFile.yml and a whole folder ignored:

/ignored
/ignoredFile.yml

Note: The .apignore file is only supported for automation packages as folders and only for deployments or executions via the Step CLI. For the Maven plugins standard approach of JAR packaging should be used instead.

Execute Automation Packages

The ap execute command allows to package and execute Automation Packages locally or in Step.

Get the list of all options and their descriptions with:

$ step ap execute help

Local execution

To execute an Automation Package locally, simply pass the --local option to the ap execute command. All Plans contained in the package will be executed locally.

Example:

step ap execute --local

Remote execution in Step

To execute an Automation Package remotely on a Step server, the step ap execute requires at least the URL of the Step server. For Enterprise Edition of Step it also requires the project and authentication Key.

Example:

step ap execute --stepUrl=http://localhost:8080 --token=<API_KEY> --projectName=JMeter_Tests

Remote executions are executed in isolation. This means that the plans contained in the Automation Package are executed on a one-off basis and in an ephemeral context that is destroyed afterward. In other words, the Automation Package and its contents are not made available on the server, but only exist temporarily during and in the context of the execution.

By default, the command ap execute starts a separate execution for each plan in the automation package.

The CLI offers the option --wrapIntoTestSet, which wraps all the plans into a TestSet at execution time. When this option is used, all the plans are executed within a single TestSet. Parallelism can be optionally controlled using --numberOfThreads.

step ap execute --stepUrl=http://localhost:8080 --token=<API_KEY> --projectName=JMeter_Tests --wrapIntoTestSet

Execute Automation Packages stored in an artifact repository

The execute command also supports the execution of Automation Packages that are stored in an artifact repository. The package option allows to specify the maven coordinates of the Automation Package as follows:

step ap execute --stepUrl=http://localhost:8080 -p "mvn:groupId:artefactId:version[:classifier:type]"

The classifier and type are optional, to define a type without a classifier you must pass and empty classifier: mvn:groupId:artefactId:version::type

Remember that your Step instance needs to be configured to access the specified artifact repository.

Execute Automation Packages with libraries

You can specify a library when executing an Automation Package. The library can be provided as a file, maven coordinates or the name of a managed library available on the target Step instance.

Example

# Using a file; note that you can mix the source for package and library, they are not related
step ap deploy -p ./java-automation-package-1.0.0.jar -l ./java-keyword-library-1.0.0.jar
# Using maven coordinate
step ap execute -p ./java-automation-package-1.0.0.jar -l mvn:ch.exense.step.testing.libraries:java-keyword-library:1.0.0
# Using a manged library
step ap execute -p ./java-automation-package-1.0.0.jar -l managed:MyCommonJavaLib -c cli.properties

Filtering Plans

Per default, the command step ap execute executes all the Plans contained in the Automation Package. To execute a subset of the Plans, the command supports different options:

Filter Plans by names

--includePlans=<includePlans> this option allows to explicitly specify a comma separated list of plan names to be executed
--excludePlans=<excludePlans> this option allows to specify a comma separated list of plan names to be excluded from the execution

Filter Plans by categories

Plans can be labeled with categories in the YAML descriptor (See Plans syntax). Following options allow to select specific Plans to be executed based on their categories:

--includeCategories=<includeCategories> The comma separated list of categories to be executed
--excludeCategories=<excludeCategories> The comma separated list of categories to be excluded from execution

Execution reports

The execution results can be fetched in different formats using following arguments:

--reportType=<reportType>: The type of execution report to be generated and stored locally, supported report types: junit, aggregated. Also, you can specify (optionally) the output destination(s): –reportType=“junit;output=file,stdout”
--reportDir=<reportDir>: The local folder to store generated execution reports can be optionally overridden

junit stands for the JUnit XML reports standard format and use a file output per default while aggregated stands for the aggregated report format of Step in a textual representation and defaulting to the standard output.

Deploy Automation Packages

The command step ap deploy allows to upload Automation Packages to a Step server. It makes all the entities contained in the Automation Package available for use in Step, and activates the contained schedules. This is the equivalent of a full “installation”.

As for the remote execution, the required parameters are the Step URL, and additionally the project and authentication Key for the Enterprise edition.

Example:

step ap deploy --stepUrl=http://localhost:8080 --token=<API_KEY> --projectName=JMeter_Tests

Deploy Automation Packages stored in an artifact repository

The deploy command also supports the deployment of Automation Packages that are stored in an artifact repository. The package option allows to specify the maven coordinates of the Automation Package as follows:

step ap deploy --stepUrl=http://localhost:8080 -p "mvn:groupId:artefactId:version[:classifier:type]"

The classifier and type are optional, to define a type without a classifier you must pass and empty classifier: mvn:groupId:artefactId:version::type

Remember that your Step instance needs to be configured to access the specified artifact repository.

Deploy Automation Packages with libraries

You can specify a library when deploying an Automation Packages. The library can be provided as a file, maven coordinates or the name of a managed library available on the target Step instance.

Example

# Using a file; note that you can mix the source for package and library, they are not related
step ap deploy -p ./java-automation-package-1.0.0.jar -l ./java-keyword-library-1.0.0.jar
# Using maven coordinate
step ap deploy -p ./java-automation-package-1.0.0.jar -l mvn:ch.exense.step.testing.libraries:java-keyword-library:1.0.0
# Using a manged library
step ap deploy -p ./java-automation-package-1.0.0.jar -l managed:MyCommonJavaLib -c cli.properties

Deploy multiple versions of the same Automation Package

You may need to deploy several versions of the same Automation Package on a single Step instance.
This is common when the system under test (SUT) exists in different versions across environments, each requiring a matching version of the automation code.

With the CLI, you specify the version name and its activation expression using the deploy options.
The activation expression determines when a given version should be selected at runtime.

Example

step ap deploy --versionName="PROD" --activationExpression="env == \"PROD\""

step ap deploy --versionName="TEST" --activationExpression="env == \"TEST\""

Considerations for Maven artifacts

The lifecycle related to Automation Packages artifact resources is documented in details in the Automation Package sources. When using the CLI, the refresh of a SNAPSHOT artifact and the reload of the Automation Packages using it, can be triggered passing the option –forceRefreshOfSnapshots to the deploy command. This option is only required if other Automation Packages in the same tenant use the same SNAPSHOT artifacts.

step ap deploy -p ./java-automation-package-1.0.0-SNAPSHOT.jar -l mvn:ch.exense.step.testing.libraries:java-keyword-library:1.0.0-SNAPSHOT --forceRefreshOfSnapshots

Deploy Libraries

You can deploy Automation Package libraries individually using the CLI, you can either provide the library as a file or maven coordinates as for other operations. This is convenient, for instance, if you want to create a common library in a global project which will be used by multiple Automation Packages deployed in different Step projects.

Examples:

# Deploy a library 
step library deploy -l mvn:ch.exense.step.testing.libraries:java-keyword-library:1.0.0
# Deploy a managed library 
step library deploy -l mvn:ch.exense.step.testing.libraries:java-keyword-library:1.0.0 --managed="MyCommonJavaLib"

CLI configuration files

All options passed to the CLI commands can also be defined in a configuration file using the exact same option names. The CLI will always load options defined in the file stepcli.properties located in your home folder if it exists. You can additionally provide additional configuration files as command line arguments. When a same option is specified multiple times, the last value provided will be used considering following resolution order:

Options specified in the home folder stepcli.properties file
Options specified in the configuration files given in arguments (from left to right)
Option specified directly as command arguments

Considering following stepcli.properties file in the home folder

stepUrl=https://stepee-sed-2870.stepcloud-test.ch
token=<API_KEY>
projectName=Common

Following configuration files jmeter_cli.properties in your project folder:

projectName=JMeter_Tests

Running following command will use the step URL and token defined in the home folder and the projectName overwritten in the jmeter_cli.properties file

step ap execute -c jmeter_cli.properties

Execution parameters configuration

Execution parameters are a special case since we want to be able to provide multiple execution parameters as key/value. Therefore, the executionParameters can be defined in multiple locations and will be all merged together. In case a key is defined multiple times, the value will be taken following the same principle as the resolution of the configuration files.

Since a single configuration file cannot contain the same executionParameters property multiple times, the | delimiter is used to define multiple execution parameters.

Example stepcli.properties file in the home folder

executionParameters=myParam1=myValue1|myParam2=myValue2

Example jmeter_cli.properties file in the home folder

executionParameters=myParam3=myValue3|myParam4=myValue4

CLI command example:

step ap execute -c jmeter_cli.properties -ep myParam5=myValue5 -ep myParam4=overwrittenValue

Will be resolved as follow:

Execute automation package with parameters: {myParam5=myValue5, myParam4=overwrittenValue, myParam1=myValue1, myParam2=myValue2, myParam3=myValue3}

Get the CLI

CLI usage

Automation Package location

Excluding Files from Automation Packages

Execute Automation Packages

Local execution

Remote execution in Step

Execute Automation Packages stored in an artifact repository

Execute Automation Packages with libraries

Example

Filtering Plans

Filter Plans by names

Filter Plans by categories

Execution reports

Deploy Automation Packages

Deploy Automation Packages stored in an artifact repository

Deploy Automation Packages with libraries

Example

Deploy multiple versions of the same Automation Package

Example

Considerations for Maven artifacts

Deploy Libraries

Examples:

CLI configuration files

Execution parameters configuration

See Also