Categories: DEVELOPER GUIDE CI CD DEV OPS ENTERPRISE

Automation Packages

The concept of Automation Packages provides a standard for defining software automation workflows for the whole DevOps lifecycle in a unified way. Following the Automation as Code paradigm, it allows developers to define software automation logic as code alongside the actual application’s code, and provide all the means to execute and deploy this logic at the different stages of the DevOps lifecyle.

Technically the Automation Package standard consist of:

Automation Packages in a nutshell

In a nutshell an Automation Package is a self-contained set of Plans and their related entities (Keywords, Parameters and Resources) that can be executed on a Step controller or deployed to it for later use.

The figure below gives a high-level overview of the content of Automation Packages, as well as the most important operations related to them.


Supported entities

Automation Packages support following entities:

  1. Keywords: Keywords encapsulate the automation logic and are the building blocks of plans. You can write keywords entirely from scratch, as well as integrate existing automation solutions.
  2. Plans: Plans define the operational logic that Step performs. They are defined in a YAML format.
  3. Parameters: Parameters in Step are the key to creation of modular workflows that can be executed in different environments, etc
  4. Schedules: Schedules define which plans are to be periodically executed. They are also defined in YAML.
  5. Resources: Plans may refer to additional resources, such as bundled data used during plan executions (e.g., Excel or CSV files containing test data).
  6. Alerting Rules: If plans fail to execute correctly (for example by failing, or by not meeting user-definable performance or other criteria), alerts can be sent using various mechanisms. Flexible rules for such circumstances may be defined, again expressed using a YAML notation.

Supported operations

At Automation Package build time, these entities are packaged into an archive file which can then be operated on. The most important operations are:

  1. Package: This operation creates an automation package from the entities. This is the equivalent of the compilation step of traditional programs.
  2. Publish: This operation publishes an automation package to an artifact repository, but does not perform any further actions. This is an optional step that allows to deploy or execute an automation package on multiple Step servers.
  3. Deploy: This operation uploads an automation package to a Step server, makes all the entities it contains available for use in Step and activates the contained schedules. This is the equivalent of a full “installation”.
  4. Execute: This operation performs a one-off execution of the plans contained in an automation package on a Step server, in a temporary isolated context. The content of the automation package is therefore executed once and then removed again, but not permanently deployed or activated. This operation is useful for instance for performing load or performance tests during the Test phase of the DevOps cycle.

Integration with CI/CD pipelines

The figure below shows how automation packages are built and used within a CI/CD pipeline.

This illustrates the following aspects of the automation packages:

  • The code of automation packages is stored in a git repository, along with the actual application to automate.
  • The automation package is built by the CI/CD pipeline together with the application itself.
  • The automation package can be deployed to an artifact repository like the application itself.
  • The execution of the plans contained in the automation package is triggered by the CI/CD pipeline at the different stages of the pipeline. For example:
    • Test: Execute the plans contained in the automation package after deployment of the application to the test environment
    • Operate: Provide Self-Service Automation services, automate recurring tasks
    • Monitor: Schedule periodic monitoring of the application after its deployment to the productive environment

Automation package descriptor

Automation Packages are defined in a declarative way using YAML alongside the automation code. The Step Automation Package YAML syntax is documented here

It supports the declaration of all the entities supported by Automation Packages (see above) in a declarative way using YAML.

Declare entities in the automation package descriptor

The full documentation of the Automation Package YAML syntax which allows to declare entities in the automation package descriptor can be found here

Declare entities in the code

Automation package entities can be either defined in a declarative way in the automation package descriptor (YAML) or in the code directly. This section focuses on the declaration of entities in the code.

Java

In addition to the declaration of entities in the automation package descriptor (YAML), Java Automation Packages also support the declaration of Keywords and Plans in the code.

Declaration of Keywords

In addition to the declaration of Keywords in the automation package descriptor (YAML), Automation packages also fully support the Keyword API to declare Keywords directly in Java. See Keyword declaration for details

Declaration of Plans

In addition to the declaration of Plans in the automation package descriptor (YAML), Java Automation packages also support the declaration of Plans in the code.

Keyword as Plan

For simple Plans made of only one Keyword, the Java annotation step.junit.runners.annotations.Plan allows to annotate Keyword methods and declare Plans out of it.

Example
public class MyTestSetUsingInlinePlans {
@Plan()
@Keyword
public void myPlanMadeOfOneKeyword() {
output.add("hello","world");
}
}

Inline plans

The Java annotation step.junit.runners.annotations.Plan allows developers to declare Plan using the Plain text syntax via annotation.

Inline plans are plain text plans that are directly defined within Java-Class using the method annotation step.junit.runners.annotations.Plan where the value of the annotation declares the Plan in plain-text syntax. The implementation of the annotated method is ignored.

Example

Here’s a simple example of a class containing one inline plan:

public class MyTestSetUsingInlinePlans {
@Plan("myKeyword")
public void myInlinePlan() {}

@Keyword
public void myKeyword1() {
output.add("hello","world");
}
}

Embed Plain text plans

In addition to the declaration of Plans as YAML, Automation Packages also support the inclusion of Plain text plans files as Jar resource.

To do so, plain-text plan files have to be added as resource in the Java project together with a Java class referencing them using the annotation step.junit.runners.annotations.Plans.

Here’s a simple example of a class referencing 2 plan files:

@Plans({"MyPlan1.plan", "MyPlan2.plan"}) //Reference 2 plans in plain-text format
public class MyTestSet1 {
}

MyPlan1.plan located as resource in the same package as the class MyTestSet1: 

"Open Chrome"
"Search in google" search="STEP"

MyPlan2.plan located as resource in the same package as the class MyTestSet1: 

"Open Chrome"
"Search in google" search="exense"

.NET

In .NET Automation Packages support the declaration of Keywords only in the code.

For the declaration of Keywords, the Keyword API is fully supported. See Keyword declaration for details

JavaScript / TypeScript

In JavaScript / TypeScript Automation Packages support the declaration of Keywords only in the code.

For the declaration of Keywords, the Keyword API is fully supported. See Keyword declaration for details

Automation package formats

With the introduction of automation packages in Step 24, a single file format (Java archive) is supported for defining automation packages, but this may be extended in the future.

JAR (Java archive)

In its JAR format the automation package consists of a standard JAR file that contains all the automation code and libraries as Java classes, as well as the automation package descriptor as YAML.

The Java automation package is built just like any regular Java .jar archive. We recommend using maven for this task, but you can use any suitable build toolchain that is capable of producing correct jar files.

Other formats

Future versions of Step may include support for other formats for automation packages, such as files specifically tailored to the requirements of .NET keywords, or an “exploded” format (consisting of raw, non-packed directory structures). However, at this time, no specific roadmap exists for such formats, and they may be added as the need for them arises.

Layout

At its core, an automation package’s definition consists of a single file named automation-package.yaml, placed in the top-level directory of the AP archive.

This file will usually contain Step plans, which in turn reference Step keywords, which may themselves have dependencies on libraries etc.

Because the automation package is self-contained, it needs to include all those dependencies, and therefore, usually the biggest part of the automation package’s content will in fact consist of compiled code or other kinds of resources required for the execution of said code.

Below are annotated examples showing the content of actual automation package files:

okhttp load test example

This is the content of the automation package (in JAR format) built from this tutorial. It contains Step keywords defined in Java, and therefore the resulting classes, as well as their transitive dependencies.

META-INF/                 jar metadata
kotlin/                   Java classes - dependencies
okhttp3/                  Java classes - dependencies
okio/                     Java classes - dependencies
org/                      Java classes - dependencies
step/                     Java classes - keywords
automation-package.yaml   Automation Package definition

K6 load test example

This is the content of the automation package (in JAR format) built from this tutorial. In this example, the keyword is defined directly in the automation-package.yaml file, simply referencing the Grafana K6 script to be executed. Therefore, the automation package itself does not need to include any further dependency; however, it will only work on Step clusters where the Step agents include a working K6 installation.

META-INF/                 jar metadata
automation-package.yaml   Automation Package definition
opencart-test.js          K6 script

 

Command Line Interface (CLI)

The current version of the automation package CLI is based on Maven. In the following, we provide short, concrete examples of how to perform specific tasks. Please refer to the Plugin documentation for the full details.

Note that these commands must be run in the context of a maven project that includes the respective step plugin and configuration.

Define an automation package

Automation packages are defined in a file called automation-package.yaml. Please see the dedicated documentation for the file format.

Execute an automation package in Step

mvn package step:execute-automation-package "-Dstep.url=https://your.step.server/" "-Dstep.step-project-name=Common" "-Dstep.auth-token=your_token_in_text_format"

Execute an automation package locally

If you wish to execute an automation package locally on the development machine (instead of a Step cluster), you may do so by defining a trivial Java JUnit Test with the step.junit.runner.Step Runner as illustrated below:

import org.junit.runner.RunWith; import step.junit.runner.Step;
@RunWith(Step.class) public class RunAutomationPackageTest {}

This JUnit test can be executed directly in the IDE, or from the command line:

mvn test -Dtest="RunAutomationPackageTest"

The Step runner executes all the Plans contained in the Automation Package.

Define Execution Parameters for local execution

If the Plans contained in the Automation Package rely on Execution Parameters, these execution parameters can be defined for the local execution using one of the following approaches:

Using the annotation @ExecutionParamers

The annotation @ExecutionParamers allows to annotate JUnit test classes in order to define execution parameters for local executions

@RunWith(Step.class)
@ExecutionParameters({"MyExecutionParam1","Value of param 1","MyExecutionParam2","Value of param 2"})
public class StepAutomationPackageRunAllTest {
    
}

Using environment variables

All environment variables matching “STEP_*” will be mapped to execution parameters. For example “STEP_MyParam” will be mapped to the execution parameter “MyParam”

Using system properties

All system properties matching “STEP_*” will be mapped to execution parameters. For example the system property “STEP_MyParam” will be mapped to the execution parameter “MyParam”

Deploy an automation package to Step

mvn package step:deploy-automation-package "-Dstep.url=https://your.step.server/" "-Dstep.step-project-name=Common" "-Dstep.auth-token=your_token_in_text_format"

Getting Started with Automation Packages

The easiest way to get started is to use one of our tutorial projects, which include a complete project definition containing a few simple keywords and plans along with a small load test definition. It should be straightforward to execute these projects and start from there by modifying them according to your needs.

See Also