Skip to main content

Writing Step Specs

A plugin must define a step spec for each step it provides, which defines all the metadata for the step: the text, description, parameters, and examples. The steps.yml file contains all the step specs for a plugin, as well as definitions for parameters and enumerations. For Java plugins, this file is located at src/main/resources/steps.yml. Cycle reads the step specs before performing any language analysis on feature files.

Step spec example​

Below is an example steps.yml file that defines a set of steps for a counter:

steps:

  - id: resetCounter
    description: 'Resets the counter to zero.'
    deprecated: false
    stepText: 'I reset the counter'
    examples: ['I reset the counter']

  - id: resetCounterSecret
    description: 'Resets the counter to the value of SECRET_VARIABLE.'
    stepText: 'I reset the counter to the secret variable'
    examples: ['I reset the counter to the secret variable']
    inputVariables: ['SECRET_VARIABLE']

  - id: incrementCounter
    description: 'Adds the given number to the counter.'
    stepText: 'I add {increment} to the counter'
    examples: ['I add 3 to the counter']

  - id: verifyCounter
    description: 'Verifies that the counter is equal to the given total.'
    stepText: 'I verify the counter is {total} within {timeout} {unit}'
    examples:
      - 'I verify the counter is 10 within 5000 ms'
      - 'I verify the counter is 10 within 5 seconds'
    categories:
      - 'Comparison'
      - 'Assertion'

  - id: assignCounter
    description: 'Assigns the counter's value to the given variable.'
    stepText: 'I assign the counter to variable {variableName}'
    examples: ['I assign the counter to variable "AndyCount"']
    categories: ['Variable Action'],
    outputVariables: ['{variableName}']


parameters:

  - name: increment
    type: number
    description: The amount to increment the counter.

  - name: total
    type: number
    description: The total value to verify for the counter.

  - name: timeout
    type: number
    description: The timeout value.

  - name: unit
    type: timeoutUnit
    description: The timeout unit.

  - name: variableName
    type: string
    description: The name of the Cycle variable.


enums:

  - name: timeoutUnit
    values: ['seconds', 'ms']

Cycle reads the step specs when it starts to parse and identify steps. Then, when running a step, it would call the "run a step" endpoint with the step ID, parameters, and variables in the request body.

Step spec fields​

Steps​

  • id
    • The ID must be unique within the plugin.
    • Cycle will connect steps to the right plugin using the plugin's name and the step ID.
  • description
    • The description for the step.
    • It should explain what the step does in plain language.
    • This description will appear in the Step Guide.
  • deprecated
    • A Boolean flag indicating if the step is deprecated (true) or fully supported (false).
    • It is an optional field.
    • If it is not provided, then the default value is false.
  • stepText
    • This is the step text template for matching CycleScript steps.
    • It does not include step keywords (like Given, When, Then, and Once).
    • It may accept parameters by name in curly braces (like {increment}).
  • examples
    • The Step Guide and auto-complete will use these examples to show how to use a step.
    • More than one example may be provided.
    • These should be string literals with no parameters.
    • They are hard-coded for simplicity.
  • categories
    • The Step Guide uses these categories as filters for narrowing the list of steps to view.
    • A category is a string literal (like 'Keyboard Action').
    • More than one category may be provided.
    • Categories may be common across plugins.
    • It is an optional field.
    • If it is not provided, then the default value is an empty list.
  • inputVariables
    • The names of Cycle variables that Cycle must pass to the step.
    • A step may receive zero-to-many variables.
    • They may be hard-coded names (like 'MY_VARIABLE').
    • They may be parameter names (like '{variableName}').
    • The wildcard '*' denotes that a step needs all current Cycle variables (like for Groovy steps).
    • It is an optional field.
    • If it is not provided, then the default value is an empty list.
  • outputVariables
    • The names of Cycle variables that the step will return to Cycle in its response.
    • They effectively act as return values for the step.
    • A step may return zero-to-many variables.
    • They may be hard-coded names (like 'MY_VARIABLE').
    • They may be parameter names (like '{variableName}').
    • It is an optional field.
    • If it is not provided, then the default value is an empty list.

Parameters​

Step parameters must be defined as part of the parameters: object. Each parameter must define the following required fields:

  • name
    • The name of the step parameter.
    • Every parameter used in step texts must be defined in the parameters object.
  • type
    • The parameter type.
    • It must be number, string, keyCombo, or one of the enumerations.
  • description
    • The step parameter description.
    • It will be used for the step guide.

Enumerations​

Step parameters may be given enumeration values (or "enums") instead of plain numbers and strings. An enum is a set of possible string values. In the example above, timeoutUnit is an enum with two possible values: seconds and ms. A step parameter typed as an enum must have one of the enum's possible values. A plugin author may specify enumerations under the enums: object. Any number of enums may be specified. An enum may be referenced by multiple step parameters.

In CycleScript, when a step parameter is an enum, the language server will make sure that the parameter's value is in the enum's set of values. If it is not, then the language server will mark the parameter with an error. Existing CycleScript steps already have enum types for parameters. An enum value may be written with or without double quotes around it.