Categories: DEVELOPER GUIDE CI CD DEV OPS ENTERPRISE

Automation Package in Java

Automation package entities can be defined in a declarative way with the automation package descriptor (YAML) as well as directly in the code for Java Automation Packages. This page focuses on the declaration of Automation Package entities in the code which is supported for Keywords and Plans.

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. In other words, keywords declared with the API are automatically part of the package without having to reference them explicitly in the YAML descriptor.

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"

Assinging Plan’s categories

Categories can be assigned to plans and later used to filters the plans which should be part of an execution. This can be done with the YAML syntax as well as directly in Java with annotation. Wherever you use the @Plan or @Plans annotattion you may assign categories to these declared plans as follow:

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

Execute automation packages locally with JUnit

With Junit 4

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 {}

With Junit 5

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 extending the step.junit5.runner.StepJUnit5 class as illustrated below:

import step.junit5.runner.StepJUnit5;
public class RunAutomationPackageTest extends StepJUnit5 {}

Run the tests

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.

Filtering plans to be executed

You can define and combine different filters to select the plans to be executed using following annotations:

  • IncludePlans: list of plan names to be executed
  • ExcludePlans: list of plan names to be excluded from executions
  • IncludePlanCategories: list of plan’s categories to be executed (i.e. plans having this categgory will be executed)
  • ExcludePlanCategories: list of plan’s categories to be excluded from execution

For local tests, these filters are specificed as annotations, here all filters types are used to illustrate the syntax:

import org.junit.runner.RunWith; 
import step.junit.runner.Step;

@RunWith(Step.class)
@IncludePlanCategories({"Playwright","JMeter","FunctionalTest"})
@ExcludePlanCategories({"PerformanceTest"})
@ExcludePlans({"My Plan name to be excluded"})
public class RunAutomationPackageTest {}

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”

Required dependencies

In order to use the annotations described on this page or for the local execution feature, one of the following dependency must be added:

    <!-- For Step OS features, Junit 4 support -->
    <dependency>
      <groupId>ch.exense.step</groupId>
      <artifactId>step-automation-packages-junit</artifactId>
      <version>your Step version</version>
      <scope>provided</scope> <!-- use test scope if you only use local execution (Junit test) feature -->
    </dependency>
        
    <!-- For Step EE features, Junit 4 support -->
    <dependency>
      <groupId>ch.exense.step-enterprise</groupId>
      <artifactId>step-automation-packages-junit-ee</artifactId>
      <version>your Step version</version>
      <scope>provided</scope> <!-- use test scope if you only use local execution (Junit test) feature -->
    </dependency>

    <!-- For Step OS features, Junit 5 support -->
    <dependency>
        <groupId>ch.exense.step</groupId>
        <artifactId>step-automation-packages-junit5</artifactId>
        <version>your Step version</version>
        <scope>provided</scope> <!-- use test scope if you only use local execution (Junit test) feature -->
    </dependency>

    <!-- For Step EE features, Junit 5 support -->
    <dependency>
        <groupId>ch.exense.step-enterprise</groupId>
        <artifactId>step-automation-packages-junit5-ee</artifactId>
        <version>your Step version</version>
        <scope>provided</scope> <!-- use test scope if you only use local execution (Junit test) feature -->
    </dependency>

Other coding languages

For other coding languages, the YAMl descriptor is used to declare all entities. The Keywords API which exists also for .NET and javascript / typescript is used to define the keywords in the code, but these keywords must be referenced in the YAML descriptor to be part of the package.

See the API Keyword declaration for details.

See Also