Categories: DEVELOPER GUIDE CI CD DEV OPS ENTERPRISE

Step CLI

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
  • Upload Automation Packages to Step and execute them in isolation
  • Deploy the content of Automation Packages to Step and enable the contained schedules

Get the CLI

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

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.

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]"

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

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 multiple versions of the same Automation Package

You may have different versions of a same automation package that you’d like to deploy and use on a single Step instance. This is often the case if the automated application is deployed with different versions on different environments; each requiring specific version of the automation code.

With the CLI you can define the version with the deploy commands, this will automatically assign a version and allows multiple deployment of the package (package uniqueness is checked based on the coupe name and version).

step ap deploy --apVersion="1.0.1"

For self-contained execution, executing a plan from a specific package version will always automatically select the sub plans and keywords from the same version. For plans created outside the package (such as plans created directly in Step) which are calling plans and keywords belonging to a versioned automation package, an activation expression is required to determine which version to use at runtime. This can be specified as follows.

In this example the version 1.0.1 will be used when the environment execution parameter is set to PROD, and 1.0.2 when it is set to TEST :

step ap deploy --apVersion="1.0.1" --activationExpr="env == \"PROD\""

step ap deploy --apVersion="1.0.2" --activationExpr="env == \"TEST\""

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:

  1. Options specified in the home folder stepcli.properties file
  2. Options specified in the configuration files given in arguments (from left to right)
  3. 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}

See Also