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

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"