Maven plugins
Description
The Step Maven plugins provide an integration with a running Step server during your build process and an easy way to integrate Step with a CI/CD pipeline.
The Step Maven plugins support the following operations:
- Deploying keyword packages to Step during the
package
phase:
Use this goal to upload (deploy) packaged jar artefact containing keywords and their dependencies to Step - Running Automation Packages on Step either:
- During the
package
phase, by uploading a built automation package directly to Step and executing it - During the
deploy
phase, by executing the content of an automation package deployed to an Artefact Repository
- During the
Usage
You must pick the maven plugin corresponding to your Step edition, either Open Source (OS) or Enterprise (EE)
To include the desired plugin in your project you need to add the appropriate dependency to the <pluginManagement>
section in your pom.xml
.
For Step OS:
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-os-maven-plugin</artifactId>
<version>${step.plugin.version}</version>
</plugin>
</plugins>
</pluginManagement>
</build>
You can check the actual list of OS plugin goals by calling the following command (from folder containig the maven module with declared step-os-maven-plugin
):
mvn step-os:help
To display the parameters of some plugin goal you can use the following command:
mvn step-os:help -Ddetail=true -Dgoal=goal-name
For Step EE:
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-ee-maven-plugin</artifactId>
<version>${step.plugin.version}</version>
</plugin>
</plugins>
</pluginManagement>
</build>
You can check the actual list of EE plugin goals by calling the following command (from folder containig the maven module with declared step-ee-maven-plugin
):
mvn step-ee:help
To display the parameters of some plugin goal you can use the following command:
mvn step-ee:help -Ddetail=true -Dgoal=goal-name
The EE maven plugin supports the following additional features which are required to communicate with Step Enterprise:
- Authentication: the plugin allows to configure the API token which is used to authenticate to Step
- Project selection (multitenancy): because a user can have access to several projects in Step, the EE version allows to select the target project for deploying and running packages
Once you have declared the desired plugin in <pluginManagement>
section, you can use it as any common Maven plugin: call the plugin goal from command line or bind this goal with some phase of maven lifecycle (in <plugins>
section of pom.xml
file).
Detailed examples for each goals and plugin versions are provided below:
Uploading keywords to a Step Server
This Maven goal deploys packaged jar containing Step keywords to the configured Step server as a Keyword Package. The plugin determines if the same Keyword Package has already been uploaded to Step earlier and updates it if found. Otherwise it creates a new Keyword Package in Step.
This plugin goal can be used on package
phase of Maven lifecycle.
For Step OS (upload-keywords-package-os Maven goal)
You need to use the upload-keywords-package-os
goal of the step-os-maven-plugin
.
This goal has the following configuration
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
url | step.url | The URL of a running Step server | true | |
customPackageAttributes | step-upload-keywords.custom-package-attrs | Custom attributes passed to uploaded package to Step | false | |
trackingAttribute | step-upload-keywords.tracking-attr | The ’tracking’ string used to identify the uniqueness of the uploaded package (if a package with the same tracking attribute already exists in step, this package will be updated) | false | ${project.groupId}.${project.artifactId} |
artifactClassifier | step-upload-keywords.artifact-classifier | The classifier of the maven artifact (jar, jar-with-dependencies, tests etc) | false | no classifier |
Example:
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-os-maven-plugin</artifactId>
<executions>
<execution>
<id>upload-package-to-step</id>
<phase>package</phase>
<configuration>
<url>http://localhost:4201</url>
</configuration>
<goals>
<goal>upload-keywords-package-os</goal>
</goals>
</execution>
</executions>
</plugin>
You can use the following command to execute the plugin goal from the module containing package artifact with step keywords:
mvn package step-os:upload-keywords-package-os "-Dstep.url=https://stepos-master.stepcloud-test.ch"
For Step EE (upload-keywords-package-ee Maven goal)
You need to use the upload-keywords-package-ee
goal of the step-ee-maven-plugin
.
The EE version supports the integration with Step EE servers and provides the following configuration parameters additionally to the OS goal:
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
stepProjectName | step.step-project-name | The name of the target project in Step | true | |
authToken | step.auth-token | The authentication token issued by the Step server | false |
Example:
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-ee-maven-plugin</artifactId>
<executions>
<execution>
<id>upload-package-to-step</id>
<phase>package</phase>
<configuration>
<url>http://localhost:4201</url>
<stepProjectName>Common</stepProjectName>
<authToken>eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhMjUyYzhhNi1kO...
</authToken>
</configuration>
<goals>
<goal>upload-keywords-package-ee</goal>
</goals>
</execution>
</executions>
</plugin>
You can use the following command to execute the plugin goal from the module containing package artifact with step keywords:
mvn package step-ee:upload-keywords-package-ee "-Dstep.step-project-name=Common" "-Dstep.url=https://stepee-master.stepcloud-test.ch" "-Dstep.auth-token=your_token_in_text_format"
Running packaged automation packages on Step Server
This maven goal runs (executes) the automation package built as a part of current maven project.
For example, you can build the maven artifact with tests
classifier containing some java methods with @Plan
and @Keyword
annotations and execute them on a Step server.
For Step OS
You need to use the run-packaged-automation-package-os
goal of the step-os-maven-plugin
.
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
url | step.url | The URL of running Step server | true | |
groupId | step-run-auto-packages.group-id | The group id of the maven artifact | false | ${project.groupId} |
artifactId | step-run-auto-packages.artifact-id | The id of the maven artifact | false | ${project.artifactId} |
artifactVersion | step-run-auto-packages.artifact-version | The version of the maven artifact | false | ${project.version} |
artifactClassifier | step-run-auto-packages.artifact-classifier | The classifier of the maven artifact (jar, jar-with-dependencies, tests etc) | false | no classifier |
description | step-run-auto-packages.description | The description of the execution, as displayed in the execution list | false | |
executionParameters | step-run-auto-packages.execution-parameters | The execution parameters to be set for the execution | false | |
waitForExecution | step-run-auto-packages.wait-for-exec | If this value is ‘false’, the execution is started asynchronously and the maven lifecyle continues without waiting the execution result. If this value is ’true’, the maven lifecycle is suspended until the execution is finished | false | true |
executionResultTimeoutS | step-run-auto-packages.exec-result-timeout-s | If the value of waitForExecution is true, this timeout (in seconds) is applied for running execution |
false | 30 |
ensureExecutionSuccess | step-run-auto-packages.ensure-exec-success | If the value of waitForExecution is true, the plugin will analyze the execution result and stop the maven lifecycle if this results is not successful |
false | true |
Example:
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-os-maven-plugin</artifactId>
<executions>
<execution>
<id>run-packaged-artifact-in-step</id>
<phase>package</phase>
<configuration>
<url>http://localhost:4201</url>
<artifactClassifier>tests</artifactClassifier>
<description>My test automation package</description>
<userId>admin</userId>
<executionParameters>
<env>PROD</env>
<PARAM_EXEC>Value</PARAM_EXEC>
<PARAM_EXEC2>Value</PARAM_EXEC2>
<PARAM_EXEC3>Value</PARAM_EXEC3>
</executionParameters>
</configuration>
<goals>
<goal>run-packaged-automation-packages-os</goal>
</goals>
</execution>
</executions>
</plugin>
To call the plugin from command line you can use the following command from the maven module where you have the packaged artifact with step automation package:
mvn step-os:run-packaged-automation-packages-os "-Dstep.url=https://stepos-master.stepcloud-test.ch"
For Step EE
You need to use the run-packaged-automation-package-ee
goal of the step-ee-maven-plugin
.
The EE version can communicate with Step EE servers and supports the following configuration parameters additionally to the OS goal:
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
stepProjectName | step.step-project-name | The name of the target project in Step | true | |
authToken | step.auth-token | The authentication token issued by the Step server | false | |
userId | step-run-auto-packages.user-id | The user id used for starting the execution | false | user of the authentication token |
Example:
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-ee-maven-plugin</artifactId>
<executions>
<execution>
<id>run-packaged-artifact-in-step</id>
<phase>package</phase>
<configuration>
<url>http://localhost:4201</url>
<artifactClassifier>tests</artifactClassifier>
<description>My test automation package</description>
<userId>admin</userId>
<stepProjectName>Common</stepProjectName>
<authToken>eyJhbGciO.....iJIUzI</authToken>
<executionParameters>
<env>PROD</env>
<PARAM_EXEC>Value</PARAM_EXEC>
<PARAM_EXEC2>Value2</PARAM_EXEC2>
<PARAM_EXEC3>Value3</PARAM_EXEC3>
</executionParameters>
</configuration>
<goals>
<goal>run-packaged-automation-packages-ee</goal>
</goals>
</execution>
</executions>
</plugin>
To call the plugin from command line you can use the following command from the maven module where you have the packaged artifact with step automation package:
mvn package step-ee:run-packaged-automation-packages-ee "-Dstep.step-project-name=Common" "-Dstep.url=https://stepee-master.stepcloud-test.ch" "-Dstep.auth-token=your_token_in_text_format"
Running deployed automation packages on Step Server
This maven goal runs (executes) automation package built and deployed to maven repository as a part of current maven project on Step server.
Contrary to the above-mentioned run-packaged-automation-package
goal, this goal doesn’t send the packaged artifact directly to the Step server. Instead of this, the plugin try to execute the given artifact from this remote repository.
For Step OS
You need to use the run-deployed-automation-package-os
goal of the step-os-maven-plugin
.
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
url | step.url | The URL of running Step server | true | |
groupId | step-run-auto-packages.group-id | The group id of maven artifact | false | ${project.groupId} |
artifactId | step-run-auto-packages.artifact-id | The id of maven artifact | false | ${project.artifactId} |
artifactVersion | step-run-auto-packages.artifact-version | The version of maven artifact | false | ${project.version} |
artifactClassifier | step-run-auto-packages.artifact-classifier | The classifier of maven artifact (jar, jar-with-dependencies, tests etc) | false | no classifier |
description | step-run-auto-packages.description | The description of automation package | false | |
executionParameters | step-run-auto-packages.execution-parameters | The execution parameters to be set for the execution | false | |
waitForExecution | step-run-auto-packages.wait-for-exec | If the value is ‘false’, the execution is started asynchronously and the maven lifecyle continues without waiting the execution result. If the value is ’true’, the maven lifecycle is suspended until the execution is finished | false | true |
executionResultTimeoutS | step-run-auto-packages.exec-result-timeout-s | If the value of waitForExecution is true, this timeout (in seconds) is applied for running execution |
false | 30 |
ensureExecutionSuccess | step-run-auto-packages.ensure-exec-success | If the value of waitForExecution is true, the plugin will analyze the execution result and stop the maven lifecycle if this results is not successful |
false | true |
stepMavenSettings | step-run-auto-packages.step-maven-settings | The name of special maven settings (configuration) describing the remote repositories (commonly specified in settings.xml file) |
false |
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-os-maven-plugin</artifactId>
<executions>
<execution>
<id>run-deployed-package-in-step</id>
<phase>deploy</phase>
<configuration>
<url>http://localhost:4201</url>
<artifactClassifier>tests</artifactClassifier>
<description>My test automation package</description>
<executionParameters>
<env>PROD</env>
<PARAM_EXEC>Value</PARAM_EXEC>
<PARAM_EXEC2>Value</PARAM_EXEC2>
<PARAM_EXEC3>Value</PARAM_EXEC3>
</executionParameters>
</configuration>
<goals>
<goal>run-deployed-automation-packages-os</goal>
</goals>
</execution>
</executions>
</plugin>
To call the plugin from command line you can use the following command from the maven module where you have the deployed artifact with step automation package:
mvn deploy step-os:run-deployed-automation-packages-os "-Dstep.url=https://stepos-master.stepcloud-test.ch"
For Step EE
You need to use the run-deployed-automation-package-ee
goal of the step-ee-maven-plugin
.
The EE version can communicate with Step EE servers and supports the following configuration parameters additionally to the OS goal:
Property (xml) | Command Line Alias | Description | Required | Default Value |
---|---|---|---|---|
stepProjectName | step.step-project-name | The name of the target project in Step | true | |
authToken | step.auth-token | The authentication token issued by Step server | false | |
userId | step-run-auto-packages.user-id | The user id registered in automation package | false | user of the authentication token |
<plugin>
<groupId>ch.exense.step</groupId>
<artifactId>step-ee-maven-plugin</artifactId>
<executions>
<execution>
<id>run-deployed-package-in-step</id>
<phase>deploy</phase>
<configuration>
<url>http://localhost:4201</url>
<artifactClassifier>tests</artifactClassifier>
<description>My test automation package</description>
<userId>admin</userId>
<stepProjectName>Common</stepProjectName>
<authToken>eyJhbGciO.....iJIUzI</authToken>
<executionParameters>
<env>PROD</env>
<PARAM_EXEC>Value</PARAM_EXEC>
<PARAM_EXEC2>Value</PARAM_EXEC2>
<PARAM_EXEC3>Value</PARAM_EXEC3>
</executionParameters>
</configuration>
<goals>
<goal>run-deployed-automation-packages-ee</goal>
</goals>
</execution>
</executions>
</plugin>
To call the plugin from command line you can use the following command from the maven module where you have the deployed artifact with step automation package:
mvn deploy step-ee:run-deployed-automation-packages-ee "-Dstep.step-project-name=Common" "-Dstep.url=https://stepee-master.stepcloud-test.ch" "-Dstep.auth-token=your_token_in_text_format"