Translating to CycleScript

A tester can translate any Chrome-recorded test into a CycleScript feature file. Translation is a two-step process: exporting the feature file, and refining the exported scenario. Refinement is important because the exported feature files should be treated as starting scripts and not finished scenarios. This page explains how to perform both the export and the refinement.

Exporting feature files

To export a recording to a CycleScript feature file, open the recording in Chrome Recorder. In Recorder's top bar, click the download icon, and choose "Cycle feature file". (Warning: This option might not appear if the browser is on a blank tab instead of an active web page.)

A file picker should open. Choose a destination for the feature file. Make sure to include a .feature extension for the filename.

Refining exported scenarios

The exported feature file will contain syntactically-correct CycleScript code, and depending on the steps, it will probably run successfully. However, there are a few key refinements to consider making to exported feature files.

Improving locators

The web element locators that appear in the feature files are generated by the Chrome Recorder itself. The Cycle extension simply interpolates them into the CycleScript steps. Whenever the Chrome Recorder provides multiple locators, the extension interpolates the first locator into the step and then adds comment lines for alternative locators. For example:

Once I click element """cssSelector:div:nth-of-type(2) > div.searchspring-result-product-name > a""" in web browser
    # Alternative locators to consider:
    # """xPath://*[@id="searchspring-outer-container"]/div[5]/div[3]/div[2]/div[3]/a"""
    # """xPath://*[text()='34 PICT-3 VW']"""

The Chrome Recorder locators will typically work, but they can be troublesome for long-term maintenance. Chrome Recorder tends to favor IDs when generating locators, which is problematic for web apps that dynamically generate IDs for elements (like Blue Yonder). XPath locators also tend to have brittle paths that heavily rely upon indexes and direct parent/child links. In these cases, a tester should write more robust, reliable locators instead of relying upon the generated locators.

Addressing untranslated steps

The Cycle extension cannot translate the following kinds of Chrome Recorder steps:

• CustomStep
• EmulateNetworkConditions
• KeyDown and KeyUp for keystrokes out of sequence
• Scroll for scrolling to an (x,y) position
• WaitForExpression

Whenever the Cycle extension discovers one of these steps in the recorded session, it will translate it as an activity step and provide comments explaining why it could not be translated. For example:

When I "press the 'Shift' key down"
    # This individual "keyDown" step cannot be translated into CycleScript.
    # The recorder failed to find a matching "keyUp" step as part of a key chord.
    # CycleScript provides steps for typing keystrokes but not holding and releasing them.
    # Please consider replacing this step with one of CycleScript's key pressing steps.

Whenever this happens, a tester should consider if the step is important:

• If yes, then the tester should consider rewriting this part of the test to make things work.
• If no, then the tester could probably remove the step safely.

Removing unnecessary steps

Recordings are not always perfect due to human behaviors. For example, while recording, a tester might click on the wrong element or enter the wrong text into a field. These kinds of unnecessary steps should be removed from the final test scenario. Ideally, they should be removed from the session in Chrome Recorder before exporting to a feature file, but they could also be removed from the exported feature file. Please watch out for unnecessary steps and remove them when they are found.

Improving browser setup

Exported feature files contain basic browser setup steps. The Cycle extension automatically adds Background and After Scenario sections to open and close a Chrome browser respectively. The Chrome Recorder automatically adds steps to set the browser window size and navigate to the first page as well. For example, a typical feature file will contain the following:

Feature: <title>

  Background:
    Given I open "Chrome" web browser

  Scenario: <title>
    When I size web browser to <width> x <height>
    Once I navigate to "<url>" in web browser
    # ...

  After Scenario:
    Then I close web browser

These browser management steps are meant to be basic and universal. However, a tester might need to tweak them. For example, they might want to change the browser type, make the browser headless, or change the window size. Be mindful of these needs.

Handling test data

Web recorders do not handle any test data concerns. Recordings simply use whatever data is in the system or provided as inputs. Testers will need to manage test data with extra system preparation or extra test steps.

Incorporating existing scenarios

CycleScript enables a test scenario to call other scenarios. In a large Cycle project, it is common for a team to write many "utility" scenarios to perform common operations. A tester might need to rewrite portions of recorded tests to call these utilities.