Categories: USER GUIDE PLANS

YAML plans

Step plans can be defined in a declarative way using YAML in addition to the existing Visual editor and to the Plain text plan. Defining plans in a declarative manner along side your automation code is recommended for full devops experience. Compared to the plain text plan format, the YAML format allows to

  • have a full coverage and bi-directionality with the visual plans
  • well structured content similar to the tree view representation in the Step UI
  • easy integration with IDEs for auto-completion and validation thanks to the corresponding JSON schema

The following documentation describes how to create and edit YAML plans using IntelliJ and our corresponding JSON Schema to activate on-the-fly suggestions and validations in the file editor.

YAML format at a glance

Before explaining how to setup your IDE, let’s compare a plain text plan and its equivalent using the YAML syntax. The latter is a bit more verbose but well structured and easy to produce with auto-completion and validation:

    ThreadGroup Threads=1 Pacing=0 MaxDuration=0 Iterations=10
"Buy MacBook in OpenCart"
End
PerformanceAssert Measurement="Buy MacBook in OpenCart" Value=10000
    version: 1.0.0
name: "Performance assert example"
root:
 testCase:
   children:
     - threadGroup:
         users: 1
         pacing: 0
         maxDuration: 0
         iterations: 10
         children:
           - callKeyword:
               keyword: "Buy MacBook in OpenCart"
     - performanceAssert:
         measurementName: "Buy MacBook in OpenCart"
         expectedValue: 10000

    You can find more samples of Yaml plans here.

    Setup your IDE for auto-completion and validation

    The Step plan YAML syntax is specified by a JSON schema, for more convenient work you can configure the embedded file editor in your IDE (IntelliJ IDEA or Visual Studio) to associate this schema with the Step YAML plans.

    The JSON schema will be published soon, for now they can be directly downloaded here:

    In IntelliJ IDEA you first have to enable the use of remote JSON Schemas as follow

    1. In IDEA settings you need to open the Languages & Frameworks, and set the Use schemastore.org JSON Schema catalog flag in Remote JSON Schemas subsection there.

    Then you can setup bindings to link the Step YAML plan files with the actual JSON Schema published to schemastore.org:

    1. In IDEA setting open the JSON Schema Mappings in Languages & Frameworks section.
    2. Find a choose the actual JSON Schema for Step YAML Plans on schemastore.org (EE or OS version)
    3. Choose the files you want to link with selected JSON Schema

    After that you can use the chosen schema in the embedded YAML editor:

    1. When you type something in the YAML editor linked with JSON Schema, IDEA shows the on-the-fly suggestions and validates entered data according to the selected JSON Schema
    2. For the current file you can change the link to the JSON Schema (switch schema from OS version to EE or update schema to the latest version)

    YAML Plan syntax

    The top-level node in YAML plan consists of the following fields:

    • version - the version of YAML plan format (json schema). This field is optional, but in YAML plan you can define the version explicitly to keep the information about json schema version you have used. Then, if you change the json schema (update to new version), but the plan is still referenced to the old version, you will get the validation error about version mismatch (you will be forced update the plan version and actualize the plan according to the chosen json schema).
    • name - the name of plan
    • root - the root control in plan (can be one of the following: sequence, testCase, threadGroup, testScenario, testSet).

    Within the root control you can specify a custom set of fields (depending on the chosen control) and some common fields:

    • nodeName - the name of control (by default equals to the type of control)
    • description - some textual description for the node
    • children - the array of child controls with the same structure as for root node, but with extended set of supported control types (supported types depend on the Step version - EE or OS, so you need to use the EE-version of JSON Schema to prepare the plan for Step EE or use the OS-version otherwise). YAML plans support all the list of controls, which you can see in UI in Step, and the json schema for YAML plans specifies which properties for which control are available.

    Dynamic values and inputs in YAML

    For any property, which can be defined as dynamic groovy value, YAML Plans support the following syntax. Let’s take a look at an example.

    version: 1.0.0
name: "Dynamic values and inputs sample"
root:
  threadGroup:
    users: 1
    pacing: 0
    maxDuration: 0
    iterations:
      expression: "someVariable"
    children:
      - callKeyword:
          keyword: "myKeyword"
      - callKeyword:
          keyword:
            expression: "'myKeyword2'"
      - callKeyword:
          keyword: "myKeyword3" 
          routing:
            - criteria1: "criteriaValue1"
      - callKeyword:
          keyword:
            expression: "'myKeyword4'"
          routing:
            - criteria1: "criteriaValue1"
          inputs:
            - stringInput:
                expression: "'abc'"
            - intInput: 777

    Here we define the threadGroup calling several keywords. For the threadGroup control we can define users, pacing, max duration and iteration. All these properties are numeric and support the dynamic value definition (using groovy syntax). In this case in YAML format you can use either the numeric constant (as for users, pacing, max duration in example above) or the dynamic groovy expression (as for iterations). The same syntax is applicable for all properties, which support the dynamic definition. For instance, you can define the keyword name as a constant (myKeyword for the first callKeyword node) or resolve the keyword name via dynamic expresson (myKeyword2 for the second callKeyword node).

    Also for callKeyword and session controls there is a special syntax to define a routing to the agent. If you need to use some routing criteria, you have to include the routing section (like for myKeyword3 or myKeyword4 keywords).

    And if the Keyword you want to call requires some input values, you also have to use the exteded syntax with inputs section (see myKeyword4). Please note that each input you define in inputs section can be defined as dynamic value (stringInput in example above) as well as a constant value (intInput in example above).

    YAML Plan usages

    The YAML Plans can be used in the same way as Plain Text Plans in [JUnit runner] (https://step.exense.ch/resources/junit-plan-runner). You only need to specify the file with .yml extension in @Plans annotation.

    @RunWith(Step.class)
@Plans({"composite-simple-plan.yml"})
public class StepRunnerYamlPlanTest extends AbstractKeyword {
}

    In the same way you can use the YAML Plans when running an Automation package.

    YAML Plans features and limitations

    The YAML Plan format allows to define all the fields presented in Step controls (nodes, which you can add to the plan in Visual plan editor) except for the following fields:

    • “dynamicName” - controls in YAML format have static names (defined in nodeName field), and by default the nodeName equals to the type of control. If in plan you have several controls of the same type, you have to define the unique nodeName for them.

    YAML Plans conversion tool

    The Step OS source code contains the Conversion Tool designed to convert plain text plans to the yaml format.

    The Tool is a simple Java console application (the YamlPlanConversionTool class). When you launch the Tool you need to specify only one parameter - the path to file system folder containing the plain text plans:

    java step.plans.simple.YamlPlanConversionTool C://projects//step/plans

    The Tool converts all plain text plans (files with .plan extension) located in the specified folder to the Yaml format (to files with the same names but with .yml extension) and puts generated files in nested /out folder.

    For successful conversion you need to have all the classes from step-plans-simple-yaml-parser module (and it’s dependencies) in classpath.

    You can also launch the Tool from IDEA. To to this, open the Step OS project and choose the YamlPlanConversionTool launcher. Then you need to open the launcher settings and specify the program argument (the above-mentioned path to plain text plans) there. After that you can click on ‘Run Configuration’ to lauch the Tool.

    If you want to convert Step EE plans, you have to run the Tool from Step EE project. To do this, please run the YamlPlanConversionTool IDEA launcher located in step-plans-parser-ext-enterprise module in the same way as for Step OS.

    See Also