Skip to main content

Determining Steps to Create

You should carefully formulate the new steps that you want to create before touching any code or OpenAPI specs. That way, you can make sure that you are creating the "right" steps for your needs. Write out the CycleScript text in full for the steps you want to create. Try writing example scenarios with them as well. See if the verbiage makes sense together with other steps. It will be much easier to change step text now than later in step plugin development.

Let's walk through an example together.

Writing a first draft​

Suppose you need to test an app for ordering coffee. You might want to write a scenario with the following steps:

Scenario: Order coffee from My Coffee App
    Given I am logged into My Coffee App
    When I navigate to the menu
    And I select a "mocha latte" from the menu
    And I accept all default options for my chosen drink
    Then I see 1 "mocha latte" in the shopping cart

These steps adhere to many of the recommended practices for steps:

  • Be understandable.
  • Be clear and concise.
  • Be composable with related steps
  • Focus on behavioral concerns (what) rather than automation concerns (how).
  • Use first-person perspective ("I-me-my") to be consistent with other CycleScript steps.
  • Use step parameters ("mocha latte", 1) to pass inputs into steps.

Refining the steps​

However, one possible weakness is ambiguity in details. For example, the step When I navigate to the menu does not state the precise menu to which to navigate. This could be problematic if (a) the My Coffee App has more than one menu, or (b) you need to test other apps with menus. If you add this step to Cycle, other testers might be confused by what menu this step targets. Therefore, it might be better to rewrite the scenario with more precise steps:

Scenario: Order coffee from My Coffee App
    Given I am logged into My Coffee App
    When I navigate to the drink menu in the My Coffee App
    And I select a "mocha latte" from the drink menu
    And I accept all default options for my chosen drink
    Then I see 1 "mocha latte" in the My Coffee App shopping cart

In this updated scenario, steps are clearer about the drink menu in the My Coffee App and the My Coffee App shopping cart. Although this extra diction may seem repetitive, it reduces ambiguity and the risk of misunderstandings.

Writing "good" steps is as much an art as it is an engineering practice. That's why it is important to write out the steps with example scenarios to review and refine them.

Focusing on behavior​

The steps we wrote focus on user-centric behaviors of the My Coffee App. Notice the verbiage that they use for behavioral concerns:

  • "navigate" to a specific menu
  • "select" a drink by name
  • "accept" default options
  • "see" the chosen drink

Notice the verbiage that was not used:

  • references to session objects
  • locators like XPaths and CSS selectors
  • math or string operations

Those are all automation concerns that should be handled within the new steps. Those details do not need to be exposed to the tester through CycleScript. There may be times that you need to write steps that expose some automation concerns, and that's fine. Just be mindful to make sure it is actually needed.