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

Declare Automation Packages Entities

Automation Packages are defined in a declarative way using YAML alongside the automation code. The Step Automation Package YAML syntax is documented with the Automation package descriptor. It is language agnostic and supports the declaration of all the entities supported by Automation Packages (see above).

For Java Automation Packages, it is possible to directly declare certain entities in the code in addition to the YAML descriptor.

Automation package formats

Step currently supports following Automation Package formats:

  • JAR (Java archive)
  • Zip
  • Folder (supported only by the Step CLI)

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.

ZIP

The ZIP format of automation packages consists of a standard ZIP archive of the Automation Package descriptor YAML file(s), and all referenced automation resources. The only constraint is that the automation-package.yaml must be at the root of the archive.

Folder (exploded)

The folder consists of the raw, non-packed directory structure of the Automation Package. It is currently only supported by the Step CLI)

Other formats

Future versions of Step may include support for other formats like .NET. 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 at the top-level of the AP archive.

This file contains the declaration of Step entities such as Step parameters, Step plans, Step keywords which in turn may refer to file resources like test data files, Keywords script files… For Java Automation Packages, keywords may also be defined as Java code and also 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.

JAR Layout

Below are annotated examples showing the content of actual automation package files created with the maven plugin CLI

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

ZIP and Folder Layout

For non-Java based packages, the structure is simpler and only contains the YAML files and any file resources. These packages are supported by the Step CLI either as folder or ZZP archive.

JMeter load test example`

This is the content of the automation package for a simple JMeter load tests. It contains, the JMeter test plan resource file, and the automation-package.yaml file declaring the JMeter keyword (referencing the JMeter test plan file) and the load scenario.

Demo_JMeter.jmx   JMeter Test Plan
automation-package.yaml   Automation Package definition

K6 load test example

This is the content of the automation package for a simple Grafana K6 load test. In this example, the keyword is declared in the automation-package.yaml file, simply referencing the 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.

automation-package.yaml   Automation Package definition
opencart-test.js          K6 script

Command Line Interface (CLI)

The CLI for Automation Packages is provided as a Maven plugin for Java based projects and as a native CLI for all other contexts.

In the following sections, we provide short, concrete examples of how to perform specific tasks with the maven plugin. Please refer to the Plugin documentation for the full details and to the Step CLI to execute these same tasks with the native CLI.

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

In the context of Java / maven project, use our simple approach leveraging Junit tests to run your package locally.

In all other context, the Step CLI is the way to go.

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"

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.

This is possible by specifying the version during the deployment of the package with either the CLI, the maven plugin or the Step UI; the package uniqueness is based on the couple Automation Package name and version.

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) calling plans and keywords belonging to a versioned automation package, an activation expression is required to determine which version to use at runtime. Like the version, the activation expression can be specified during the deployment.

See more concrete example and usages in the Step CLI

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