1. CycleScript is designed to be a common language between business stakeholders and technical engineers. In order to ensure this, CycleScript should not be written like a programming language, but like a naturally readable standard operating procedure using business and comment steps.
   
1. Here’s an example of harder to read code:
   

   Given I assign 0 to variable "x"
   While I verify number $x is less than 5
   Then I execute scenario "Unload the Truck"
   And I increase variable "x" by 1
   EndWhile
   

1. The previous example lacked indentation, didn’t have a step to describe the goal of the code chunk, and used ambiguous variable names. Here’s an example of easier to read code:
   

   Given I "unload the truck five times"
       Given I assign 1 to variable "times_unloaded"
       While I verify number $times_unloaded is not equal to 5
           Then I execute scenario "Unload the Truck"
           And I increase variable "times_unloaded" by 1
       EndWhile
   

1. Before you perform any action in CycleScript, first validate that you are where you want to be - whether that’s a web page, terminal screen, or application. Confounding variables such as system lag, application errors, and unexpected behavior can affect state and therefore break your action.
   
1. Use steps with a within clause to validate state while accounting for variable response times.
   
2. Use an I see cursor step in the terminal before interacting with it to ensure the terminal screen has fully rendered.
   
3. Use an I see element step in the web before interacting with the element to ensure the web page has rendered correctly and entirely.
   
2. Within reason, extract code duplication to their own scenarios, so that maintenance of that logical component is centralized. This keeps code clean by reducing repetition.
   
1. Here’s an example of WET pseudo-code:
   

   Scenario: Plan Shipment from Order
   Given I "obtain the Order Number"
       Given I "obtain a dynamic value from the screen I am on"
       When I "build a custom query by concatenating that dynamic value"
       And I "query the appropriate data source for the order number"
   
   Then I "plan shipment from order"
       Given I "navigate to the correct screen"
       And I "open the shipment planning modal"
       When I "select the order"
       And I "plan the shipment"
       Then I "verify the shipment is planned"
   
   Scenario: Allocate Shipment
   Given I "obtain the Order Number"
       Given I "obtain a dynamic value from the screen I am on"
       When I "build a custom query by concatenating that dynamic value"
       And I "query the appropriate data source for the order number"
       
   Then I "allocate shipment"
       Given I "navigate to the correct screen"
       And I "open the allocation modal"
       When I "filter by the order number"
       And I "select the shipment"
       And I "allocate it"
       Then I "verify the shipment is allocated"
   

1. The functionality to obtain the order number can be extracted. Here’s an example of DRY pseudo-code:
   

   Scenario: Plan Shipment from Order
   Then I "plan shipment from order"
       Given I "navigate to the correct screen"
       And I "open the shipment planning modal"
       When I "select the order"
       And I "plan the shipment"
       Then I "verify the shipment is planned"
   
   Scenario: Allocate Shipment
   Then I "allocate shipment"
       Given I "navigate to the correct screen"
       And I "open the allocation modal"
       When I "filter by the order number"
       And I "select the shipment"
       And I "allocate it"
       Then I "verify the shipment is allocated"
   
   Scenario: Obtain Order Number
   Given I "obtain the Order Number"
       Given I "obtain a dynamic value from the screen I am on"
       When I "build a custom query by concatenating that dynamic value"
       And I "query the appropriate data source for the order number"
   

1. Rather than reinventing the wheel for standard implementations and practices, stay consistent with existing CycleScript and conventions.
   
1. Here’s an example of inconsistent coding practices:
   

   @wip @receive-pallet
   Scenario: Receive Pallet
   # DESCRIPTION: THIS CASE RECEIVES A PALLET
   # INPUT: SPECIFY THE LODNUM TO RECEIVE
   # OUTPUT: THE LODNUM WILL BE RECEIVED
   Given I "navigate to the receiving terminal screen"
       When I "navigate there"
       And I "type menu options"
   
   And I "receive the pallet"
       When I "type in the lodnum"
       And I "perform countback"
       And I "deposit it"
   
   @wip @receive_pallet
   ################################################
   # Scenario: Receive Case
   # Description:  This scenario, given a load
   #               number, will start at the 
   #               Undirected Menu and go receive
   #               the case.
   # Input:  $lodnum
   # Output: N/A.
   ################################################
   Scenario: Receive Case
   Given I "navigate the receiving terminal screen"
     When I "navigate there"
     And I "type menu options"
   
   And I "receive the pallet"
     When I "type in the lodnum"
     And I "perform countback"
     And I "deposit it"
   

2. You can see that both scenarios use different indentation conventions, scenario headers, and tags. This makes code harder to maintain over time - especially as projects scale. Pick one standard for everyone and stick to it.
   
2. On a Feature File level, separate public and private scenarios via tags to expose and hide external and internal functionality to other features. This helps convey the developer’s intent and allows the external API to have consistency, while the internal API can change over time with development.
   
1. Here’s an abridged example of how to do so:
   

   Feature: Count Back
   
   @wip @public
   Scenario: Count Back
   Given I "calculate the remainder"
       Given I execute scenario "Screen Scan"
       When I execute scenario "Calculate Remainder"
   
   When I "perform Count Back"
       When I execute scenario "Screen Input"
   
   ###############################
   # Private Scenarios:    
   ###############################
   @wip @private
   Scenario: Screen Scan
   When I "extract the pallets, cases, and eaches listed on the screen"
   
   @wip @private
   Scenario: Screen Input
   When I "input the pallets, cases, and eaches remaining"
   
   @wip @private
   Scenario: Calculate Remainder
   Given I execute scenario "Check Database for Picked"
   When I "calculate the remainder in the location"
   
   @wip @private
   Scenario: Check Database for Picked
   When I "query the database to determine how much was picked"
   

3. You can see certain scenarios, below a comment header, are tagged as private. The intent of the developer is that whoever imports this scenario, only the scenario Count Back should be called. This can be done for a variety of reasons, like the private scenarios having internal dependencies.
   

Terminology

Customer Terminology

1. A Scenario is a logical block of actions defined in Cycle.
   
2. A Feature File contains Scenarios.
   
3. A Utility is a scenario or feature file that is imported and called by a Test Case.
   
4. A Test Case is a scenario or feature file that performs a standalone Unit or End-to-End Test.
   
5. A Regression Test is a collection of one or many Test Cases that run standalone or on a playlist.
   
6. A Volume Test comprises of one or many Test Cases which are run concurrently by independent workers in a grouptest.
   
7. Continuous Testing is the process of running Regression or Volume tests on a set trigger, usually changes to the configuration, code, and/or environment of an application.
   

Industry Jargon

1. A Scenario is the same thing as a Function, Method, and a Routine.
   
2. A Utility Scenario is the same thing as a Helper Scenario and a Utility.
   
3. A Utility Scenario is always a @WIP Scenario.
   
4. A Utility Feature File is a Feature File that only contains Utility Scenarios.
   
5. A Test Case is sometimes referred to as a Script.
   
6. One or multiple Test Cases can be in a single Feature File.
   
7. A Feature File with a single scenario that is a Test Case may also be referred to as a Test Case.
   
8. Environment Variables are variables called in an Environment.feature file, typically in the Background. They are instantiated once and expected to remain static.
   

Feature File Structure

1. Feature Header
   
1. Licensing and Copyright Information
   
2. Meta-Data
   
2. Feature Declaration
   
3. Background
   
1. Background Header
   
2. Dependency Imports
   
3. Environment Setup
   
4. Setup Functions
   
4. After Scenario
   
1. After Scenario Header
   
2. Interface Logout
   
3. Data Cleanup, if applicable
   
4. Reporting Mechanisms, if applicable
   
5. Scenario(s) and Scenario Outline(s)
   
1. Scenario Header
   
2. Scenario Implementation
   
1. Interface Login
   

Naming Conventions

1. Folders, Feature Files, and Scenarios use title casing.
   
1. Title Casing Tool
   
2. Examples:
   Utilities
   Web Services
   Receiving Staging
   Deposit Load
   Find Part for All Shipments
3. Title Casing - capitalize everything but:
   
1. Articles:
   
1. a
   
2. an
   
3. the
   
2. Coordinate conjunctions:
   
1. for
   
2. and
   
3. nor
   
4. but
   
5. or
   
6. yet
   
7. so
   
3. Prepositions: (According to the Chicago Manual of Style)
   
1. such as at
   
2. around
   
3. by
   
4. after
   
5. along
   
6. for
   
7. from
   
8. of
   
9. on
   
10. to
    
11. with
    
12. without
    
2. Environment Variables, Variables, and Script Filenames should use be lowercase, with words separated by underscores.
   
1. Examples:
   loop_count
   generate_lpn.msql
   unidentifiable

Headers

Feature Headers

Test Case Examples (CSV) Headers

Background Headers

After Scenario Headers

Private Scenario Headers

Scenario Headers

Dataset File Headers

MSQL Script File Headers

Groovy Script File Headers

Step Usage

Keywords

1. Given is used to verify and transition the application to the intended state - whether that’s the correct web page, terminal screen, importing utilities, and/or collecting the necessary background data - to perform the action.
   
2. When performs the actual action - whether that’s clicking a certain button, inputting certain data, and/or performing the primary calculation.
   
3. Then validates the result of the action - through a database query, image validation, and/or other mechanisms.
   
1. Subsequent to a Business/Activity/Comment Step, the Then keyword can be used if the relevant code chunk is small and would flow more smoothly verbally.
   
4. But is used for negative validation.
   
5. And is commonly appended to any of the above keywords as a continuation if the task can not be completed in one step.
   
1. In the context of a Control Structure, like an If, Else, and While, it acts as a conjoint clause, meaning the condition associated with the And is also calculated alongside the condition associated with the If, Else, and While.
   
2. In this example, please note that the And is on the same indentation level as the Control Structure keyword:
   

   While I "verify that there are still items to receive"
   And I "verify that the items are not damaged"
       Then I "receive an item"
   EndWhile
   
   If I "am logged into the Terminal"
   And I "am logged in as a handheld device"
       Then I "do handheld work"
   EndIf
   

6. Given, When, Then, But, and And should form a logical hierarchy at all times - at their indentation level. You should never use two keywords, other than And, in the same User Story.
   
1. Here is an example of two different layers of indentation levels having logical hierarchy:
   

   Given I "navigate to the Receiving Menu"
       Given I "open the terminal"
       When I "login"
       And I "input the menu option for the Receiving Menu"
       Then I "validate I am at the Receiving Menu"
       
   When I "begin Receiving"
       Given I "query the database for the receiving line"
       When I "input the receiving data"
     
   Then I "validate the Receiving process"
       Then I "validate that the line has been received"
       
   And I "exit the Receiving Menu"
       Given I "return to the Undirected Menu"
       When I "logout of the Terminal"
       Then I "validate I am logged out"
   

2. The first layer of indentation has its own logical hierarchy of keywords, and each chunk of the second layer of indentation also has its own logical hierarchy of keywords.
   
7. Once replaces the Then and Given keywords for validation when a standard wait time, configurable in the Project Settings and defaulted to 120 seconds, needs to be enforced. This would be because the execution time of the step is unknown or variable due to latency or other reasons. Judicious use of the Once keyword allows for robust tests that take into consideration different systems' delays and will avoid the usage of many within clauses or I wait steps in your code.
   
1. Here is an example of using Once to replace Given and Then keywords:
   

   Given I "open the policy screen"
       Given I "click the policy menu option"
       Once I "see the policy screen"
        
   When I "change a policy"
       Once I "see the policy tables have loaded"
       And I "click on a policy"
       When I "change the policy's value"
       Once I "validate the policy has changed in the database"
   

Steps

1. Use in app, in web browser, in element, and in terminal steps instead of generic steps - affix your steps with the most specificity possible.
   
2. We advise using I wait as rarely as possible.
   
3. If an I wait step is necessary, use the I "<TEXT>" which can take between <NUMBER> seconds and <NUMBER> seconds step instead - as this is more semantic for both maintainability and the resulting reports.
   
4. Always use I verify screen is done loading in terminal within <NUMBER> seconds after performing an action in the terminal and before a subsequent action.
   
5. Use I type option for “<MENU_NAME>” menu in terminal instead of manual number entry.
   
6. Use I execute scenario instead of inline scenario calls - scenario calls become more evident with this approach.
   
7. Never declare wait times inline - use Environment Variables instead.
   
8. Always validate that a variable is assigned before validating its value.
   

   If I verify variable "example" is assigned
   And I verify text $example is equal to "VALUE"
       Then I "do something"
   EndIf
   
   If I verify variable "example2" is assigned
   And I verify number $example2 is equal to 0
       Then I "do something"
   EndIf
   

Business Steps

Code Formatting

1. These formatting rules are designed to make CycleScript readable and follow the existing conventions that the editor already uses.
   
2. Here is a series of rules to follow to ensure written CycleScript maximizes legibility:
   
3. Use Forward Slashes for File Paths.
   
4. Business/Activity/Comment Steps should describe and precede an indented code block.
   
5. Business/Activity/Comment Steps and their code blocks should be separated by a single newline.
   
6. Each layer of indentation, excluding While, If, and Else code blocks should have their own logical hierarchy of keywords to form a logical user story.
   
7. While, If, Elsif, and Else code blocks should all be indented.
   
1. Conjoint And keywords used in conjunction with a Control Structure should be on the same indentation level.
   
8. EndWhile and EndIf should have the second word capitalized to be consistent with Cycle’s auto-fill mechanism.
   
9. Feature/Background/After Scenario/Scenario declarations and their associated headers have no separation.
   
10. Scenario Outlines and Data Sources and their implementation should be separated by a single newline.
    
11. Tabs should consist of four spaces - the Cycle editor interprets a tab keystroke as four spaces.
    
12. Capitalize keywords.
    

    Given I "am correct"
    but I "am incorrect and unprofessional looking"
    

13. Capitalize the “i” in the step.
    

    Given I "am correct"
    But i "am incorrect"
    

14. Do not leave extra spaces between words in a Cycle step.
    

    Given I "am correct"
    But      I "             am        incorrect" 
    

15. Casing of the remainder of the step should be consistent with Cycle’s auto-fill mechanism.
    

    # One of these is different than the others.
    Then I type option for "Load Receive" menu in terminal
    Then I TYpE oPtION FoR "LOAd ReCeIvE" MENU in TeRmINaL
    

Project Structure

1. Data
   
1. The Data folder contains flat and static data that is used when performing processes. Note the distinction between Test Case Inputs which is flat and static data that is used to drive tests.
   
2. Some examples of subfolders include Interfaces, Locators, and Serial Numbers, which contain XML Transaction Files, xPath Mapping CSVs, and Serial Number TXT Files.
   
2. Data Extract Models
   
1. The Data Extract Models folder contains .cycextract files used to pull data from the specified environment with the Extract Tool dialog.
   
3. Datasets
   
1. There are Base and Custom sub directories to provide a user driven layer.
   
2. The Datasets folder should contain a semantically named folder for each Dataset.
   
4. Documentation
   
1. Test Specifications
   
1. Test Case Specifications lists all the Test Cases and associated meta-data.
   
2. Utilities Specifications lists all the Utilities and associated meta-data.
   
2. The Cycle Bundle User Guide is available here.
   
5. Environments
   
1. The Environments folder contains a folder for each Environment the project can interface with. Each of these folders contain a default Environment CSV of key-value pairs and an Environment Override CSV of key-value pairs.
   
2. The Environment.csv points to the Environment that the project uses on a general basis.
   
3. Wait Times are defined here in a CSV file.
   
6. Playlists
   
1. There are Base and Custom sub directories to provide a user driven layer.
   
2. The Playlists folder contains .cycplay files which represent a series of test cases.
   
7. Scripts
   
1. The scripts folder should be divided into additional folders for different languages if appropriate.
   
2. There may be a Groovy and a MSQL folder - the relevant scripts should be stored accordingly.
   
3. There are Base and Custom sub-directories to provide a user-driven layer.
   
8. Test Case Inputs
   
1. The Test Case Inputs folder contains CSV files mapped to a test case that represent the data elements needed to execute the test.
   
2. Details
   
1. The Details folder contains any CSV files mapped to a Test Case Input CSV.
   
9. Test Cases
   
1. The Test Cases folder contains the Test Case feature files.
   
2. There are Base and Custom sub directories to provide a user driven layer.
   
10. Utilities
    
1. The Utilities folder contains Utility feature files.
   
2. There are Base and Custom sub-directories to provide a user-driven layer.
   
11. README.md
    
1. The README is a special git file that is displayed on the project repository page.
   
2. It should summarize the project, any special requirements, and any other relevant meta-data such as the Cycle version, JDA WMS version, release information, and project usage.
   
12. CONTRIBUTING.md
    
1. The CONTRIBUTING file is a special git file. It should delineate the CycleScript coding conventions deviant to this document, as well as the git workflow adopted for the project.
   
13. .gitignore
    
1. The gitignore file should include the reports folder so reporting isn’t version controlled and the Environment Override files so user-specific configurations are not committed to version control.
   

Addendums

1. Usage of xPaths
   
1. Avoid absolute xPaths - these are more prone to break given updates to a web page.
   
2. Use relative xPaths with semantic fields - these give more insight to what the xPath is grabbing.
   
3. Avoid using auto-generated IDs - these will break every time a web page updates.
   
2. Feature File Width
   
1. We advise your text editor be set to 80 columns width for ease of readability.
   
3. Keyboard Shortcuts
   
1. Use Keyboard Shortcuts via CycleScript if and only if they are necessary.
   
4. Usage of Groovy/MOCA
   
1. If your test includes an inline Groovy or MOCA statement that requires horizontal scrolling - move the logic into a script.
   
2. Use Cycle Steps instead of Groovy logic if the number of Cycle steps is equivalent to the lines of Groovy logic.
   
1. Here’s an example of what should be a Cycle step:
   

   # This is a groovy one-liner that should be a Cycle step! 
   # This is harder to read for non-technical users and starts a groovy runtime.
   Given I execute groovy "count = count + 1"
   
   # This is a Cycle one-liner that is the equivalent of the above.
   # This reads inline with CycleScript syntax.
   Given I increase variable "count" by 1