Keyword Usage Guidelines
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.
When performs the actual action - whether that’s clicking a certain button, inputting certain data, and/or performing the primary calculation.
Then validates the result of the action - through a database query, image validation, and/or other mechanisms.
- 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.
But is used for negative validation.
And is commonly appended to any of the above keywords as a continuation if the task can not be completed in one step.
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.
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
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.
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"
- 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.
The Once keyword has some limitations regarding screenshots. In place of this, we advise adding an explicit within clause with an Environment variable set to 30 seconds to allow for robust tests that take into consideration different systems' delays. You should always validate state before performing an action.