Using Cycle Properties

What are Cycle properties?

Step plugins accept inputs for steps from three sources:

1. CycleScript step parameters
2. Cycle variables
3. Cycle properties

These mechanisms are defined in the Writing OpenAPI Specs page.

Cycle properties are special values provided by the Cycle engine. They come from sources such as Cycle project settings and execution settings. For example, _CYCLE_DEFAULT_OUTPUT_DIR is the Cycle property for the current Cycle project's default output directory where screenshot files are saved.

Each Cycle property has a name that starts with _CYCLE_. They can have the same types as variables: string or number. Steps in a step plugin can require a Cycle property as an input by its name, just as if it were a regular Cycle variable. For example, the following step requires _CYCLE_DEFAULT_OUTPUT_DIR as a request body input:

  /sessions/start-local:
    post:
      tags: [WebDriver]
      operationId: startLocal
      x-cycle-steps:
        - I open {browser} web browser
      x-cycle-step-ids: [138]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                browser:
                  $ref: "#/components/schemas/BrowserType"
                _CYCLE_DEFAULT_OUTPUT_DIR:
                  description: Absolute path to the default output directory for screenshots.
                  type: string
              required:
                - browser
                - _CYCLE_DEFAULT_OUTPUT_DIR
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepResponse'

Supported properties

Warning: Cycle does not provide any Cycle properties in version 2.20. Below is a list of Cycle properties that will be supported starting in version 2.21.

Property Name	Type	Required	Value	Source	Cycle Version Added
_CYCLE_CREDENTIALS_USERNAME _CYCLE_CREDENTIALS_PASSWORD	string	required	Username and password values for the credential name given by the CREDENTIALS_NAME parameter. See Cycle properties for credentials.	CycleScript step	2.21
_CYCLE_DEFAULT_OUTPUT_DIR	string	required	Absolute path to the default output directory for screenshots.	Cycle project	2.21
_CYCLE_SAVE_FAILURE_SCREENSHOTS	boolean	required	If true, automatically capture screenshots whenever a web step fails.	WebDriver execution settings: "Save failure screenshots"	2.21
_CYCLE_WEBDRIVER_CLOSE_BROWSER	boolean	optional	Defaults to false. If true, automatically quit the WebDriver session at the end of each scenario if it has not yet been quit.	WebDriver execution settings: "Close browsers after execution"	2.21
_CYCLE_WEBDRIVER_CHROMIUM_SWITCHES	string	optional	Additional command line switches (or "arguments") to provide when initializing WebDriver sessions for Chromium browsers (Chrome and Edge). Put all switches into a one-line string.	WebDriver execution settings: "Additional switches for Chrome and Edge"	2.21
_CYCLE_WEBDRIVER_DEFAULT_TIMEOUT	integer	required	The default timeout value (in milliseconds) for all WebDriver interactions that perform waiting. If not provided, it defaults to 0 (meaning no waiting). Many steps may override this setting with within X seconds suffixes.	WebDriver execution settings: "Default waiting timeout (ms)"	2.21
_CYCLE_WEBDRIVER_FINDER_STRATEGY	string enum: normal or frame	required	The strategy that WebDriver steps will use for finding elements on a page. normal means locate directly from the root (like all other web testing tools). frame means recursively search through the page and all iframes on the page (the the original Cycle web steps).	WebDriver execution settings: "Element finding strategy"	2.21
_CYCLE_WEBDRIVER_HEADLESS_CHROME	boolean	required	If true, run Chrome in headless mode. This applies for both local and remote browser sessions.	WebDriver execution settings: "Run Chrome headlessly"	2.21
_CYCLE_WEBDRIVER_HEADLESS_EDGE	boolean	required	If true, run EDGE in headless mode. This applies for both local and remote browser sessions.	WebDriver execution settings: "Run Edge headlessly"	2.21
_CYCLE_WEBDRIVER_PATH_CHROME	string	optional	The absolute path to the Chrome browser to use. If given, the step plugin should override the Chrome browser path that WebDriver uses. If not given, it should not perform any customization and just use the default version of Chrome on the local machine.	WebDriver execution settings: "Custom Chrome browser location"	2.21
_CYCLE_WEBDRIVER_PATH_CHROMEDRIVER	string	optional	The absolute path to ChromeDriver. If not given, the step plugin should fall back on the system PATH variable or Selenium Manager.	WebDriver execution settings: "ChromeDriver"	2.21
_CYCLE_WEBDRIVER_PATH_EDGEDRIVER	string	optional	The absolute path to Microsoft Edge WebDriver. If not given, the step plugin should fall back on the system PATH variable or Selenium Manager.	WebDriver execution settings: "Microsoft Edge WebDriver"	2.21
_CYCLE_WEBDRIVER_PATH_IEDRIVER	string	optional	The absolute path to InternetExplorerDriver. If not given, the step plugin should fall back on the system PATH variable or Selenium Manager.	WebDriver execution settings: "InternetExplorerDriver"	2.21

Credentials properties

Cycle can store username and password credentials by a key name. If a step requires credentials, then it must declare a step parameter named CREDENTIALS_NAME for the key name as well as request body parameters for _CYCLE_CREDENTIALS_USERNAME and _CYCLE_CREDENTIALS_PASSWORD. The Engine will use the step parameter value for CREDENTIALS_NAME to look up the credentials and then pass them into the step as the _CYCLE_CREDENTIALS_USERNAME and _CYCLE_CREDENTIALS_PASSWORD variables.

The step below shows how to pass in credentials properties:

  /sessions/start-local-creds:
    post:
      ...
      x-cycle-steps:
        - I open Chrome web browser using basic authentication with saved credentials {CREDENTIALS_NAME}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                CREDENTIALS_NAME:
                  type: string
                _CYCLE_CREDENTIALS_USERNAME:
                  type: string
                _CYCLE_CREDENTIALS_PASSWORD:
                  type: string
                  format: password
                ...
              required:
                - CREDENTIALS_NAME
                - _CYCLE_CREDENTIALS_USERNAME
                - _CYCLE_CREDENTIALS_PASSWORD
                ...
      responses:
        ...