Introduction:
A common format for scenarios is Given/When/Then. The Gherkin language revolves around the Given/When/Then organization. Scenarios can be written in Gherkin in many variations, each of which has a different shade of meaning. These shades I’ve denoted as outline, values, domain terms, table values, calculation, and chatty.
Having worked on ATDD/BDD with teams in multiple industries, I’ve seen numerous variations. I’ve found these are common. Others may have found different shades and I’d love to hear about them.
Outline:
Scenario: Withdraw cash from ATM Given customer has account When cash requested from ATM Then cash is dispensed
The Outline form describes a scenario in free text without any example values. It is a structured alternative for acceptance criteria. Given states the pre-conditions or setup; When describes an action or event; Then gives the post-conditions or expected results.
For domains that are well understood by the triad (customer, developer, tester), it can sufficiently document the requirement. For others, it can be too abstract with the probability of a lot of misunderstanding.
Values
The Values form adds specific values to the scenario.
Scenario: Withdraw cash from ATM Given customer has account When $20 requested from ATM Then $20 is dispensed.
These values help in creating specific pass/fail tests for the scenario. If $20 does not come out of the ATM, the test fails.
Gherkin with values aids in discovering additional scenarios such as business rules/ calculations and/or other pre-conditions/post-conditions. For instance:
Scenario: Withdraw cash from ATM Given customer has account with $100 When $20 requested from ATM Then $20 is dispensed And account reduced to $80
Domain Terms
Agreeing on domain terms is an important aspect of scenario creation. Domain terms often do not appear in the Values form. Explicit domain terms usually beat implicit domain terms and decreases misunderstanding of requirements. Here’s an example of the explicit Domain Terms form:
Scenario: Withdraw cash from ATM Given customer has account balance of $100 When requested withdrawal amount of $20 is made Then dispensed amount is $20 And account balance is reduced to $80
An alternative way of making domain terms standout is to use a scenario outline, such as:
Scenario Outline: Withdraw cash from ATM Given customer with < Account Balance > When ATM request is < Withdrawal Amount> Then ATM response is <Dispensed Amount> and <New Account Balance> Examples: |Account Balance|Withdrawal Amount|Dispensed Amount|New Account Balance| | $100 | $20 | $20 | $80 |
The advantage of explicit domain terms is they can be used for naming attributes and parameters in the implementation. This decreases the impedance between requirements and code which aids in maintenance.
Table Values
Although the domain terms appear in the preceding form, the scenario could be re-written with tables to separate them out. The Table Values form looks like:
Scenario: Withdraw cash from ATM Given customer with: | Account Balance | | 100 | When ATM request is: | Withdrawal Amount |$20 | Then ATM response is: | Dispensed Amount | Account Balance | | $20 | $80 |
Now the domain terms stand out – Account Balance, Withdrawal Amount, Dispensed Amount. The tables may be in either orientation. One convention is to use horizontal tables for Given/Then and vertical tables for When.
Often customers who have experience with using spreadsheets such as Excel find it easier to read the Table Values form over the Values form.
One advantage of using tables is that they can easily be expanded for more terms without having to alter other aspects of the scenario. Here’s a non-happy scenario:
Scenario: Attempt withdrawal with insufficient funds. Given customer with: | Account Balance | | $100 | When ATM request is: | Withdrawal Amount |$120 | Then ATM response is: | Dispensed Amount | Account Balance | Message | | $0 | $120 | Insufficient Funds |
Calculation:
This form gives variations of a calculation or business rule. Calculation or business rule scenarios are different from flow scenarios. In a flow, such as withdrawing cash, the Given gives a necessary pre-condition such as an account with a balance. A calculation or business rule does not require pre-conditions. It simply converts inputs to one or more outputs.
Suppose there was a business rule that specified a transaction fee based on the withdrawal amount and the number of transactions on a day. Here are some examples / tests of the business rule with the input in the When:
Scenario Outline: Determine Transaction Fee Given ATM request is being processed When ATM request is < Withdrawal Amount> and < Number of Daily Transactions > Then ATM response is < Transaction Fee > Examples: | Withdrawal Amount|Number of Daily Transactions|Transaction Fee | | $200 | 2 | $2 | | $100 | 1 | $0 |
Alternatively, the input could be shown in the Given, such as:
Scenario Outline: Determine Transaction Fee Given ATM request is < Withdrawal Amount> and < Number of Daily Transactions > When request is processed Then ATM response is < Transaction Fee > Examples: | Withdrawal Amount|Number of Daily Transactions|Transaction Fee | | $200 | 2 | $2 | | $100 | 1 | $0 |
A more compact form of a business rule could be:
Scenario: Determine Transaction Fee Business Rule Given inputs when fee computed then fee is | Withdrawal Amount|Number of Daily Transactions|Transaction Fee | | $200 | 2 | $2 | | $100 | 1 | $0 |
In either case, the domain terms for both the input and output of the business rule are explicitly specified.
Chatty:
Scenario: Withdraw cash from ATM Given I have $100 in my account When I access the ATM with my card And I select withdraw money And I enter $20 for the amount And I hit the enter button Then $20 comes out of the ATM And my account goes down to $80
This form describes every single action of a user interface. If the exact steps of a user interaction are important, then this is a way of recording them. However, for many people, this form is too chatty having many more words than necessary to document the scenario.
Summary:
Six shades of Gherkin have been shown – outline, values, domain terms, table values, calculation, and chatty. For a particular scenario, the Gherkin is not fixed. As you go from exploration of stories to formation of tests, you might start with an Outline shade, alter it to a Values shade and then turn that into a Table Values shade. Or you might start with a Chatty shade and cut it down to a Values shade. The key is having the scenarios contain necessary and sufficient detail for everyone in the triad to have a clear understanding.