{"id":139,"date":"2018-07-23T18:56:44","date_gmt":"2018-07-23T18:56:44","guid":{"rendered":"https:\/\/kenpugh.com\/blog\/?p=139"},"modified":"2018-07-23T18:57:51","modified_gmt":"2018-07-23T18:57:51","slug":"six-shades-of-gherkin","status":"publish","type":"post","link":"https:\/\/kenpugh.com\/blog\/six-shades-of-gherkin\/","title":{"rendered":"Six Shades of Gherkin"},"content":{"rendered":"

Introduction:<\/h4>\n

A common format for scenarios is Given\/When\/Then.\u00a0\u00a0 The Gherkin language revolves around the Given\/When\/Then organization.\u00a0 Scenarios can be written in Gherkin in many variations, each of which has a different shade of meaning.\u00a0\u00a0\u00a0 These shades I\u2019ve denoted as outline, values, domain terms, table values, calculation, and chatty.<\/p>\n

<\/p>\n

Having worked on ATDD\/BDD with teams in multiple industries, I\u2019ve seen numerous variations.\u00a0 I\u2019ve found these are common.\u00a0\u00a0 Others may have found different shades and I\u2019d love to hear about them.<\/p>\n

Outline:<\/h4>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven customer has account\r\nWhen cash requested from ATM\r\nThen cash is dispensed<\/pre>\n
The Outline form describes a scenario in free text without any example values.\u00a0\u00a0 It is a structured alternative for acceptance criteria.\u00a0 Given states the pre-conditions or setup; When describes an action or event; Then gives the post-conditions or expected results.<\/p>\n
For domains that are well understood by the triad (customer, developer, tester), it can sufficiently document the requirement.\u00a0\u00a0 For others, it can be too abstract with the probability of a lot of misunderstanding.<\/p>\n
Values<\/h4>\n
The Values form adds specific values to the scenario.<\/p>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven customer has account\r\nWhen $20 requested from ATM\r\nThen $20 is dispensed.<\/pre>\n
These values help in creating specific pass\/fail tests for the scenario.\u00a0\u00a0 If $20 does not come out of the ATM, the test fails.<\/p>\n
Gherkin with values aids in discovering additional scenarios such as business rules\/ calculations and\/or other pre-conditions\/post-conditions. \u00a0For instance:<\/p>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven customer has account with $100\r\nWhen $20 requested from ATM\r\nThen $20 is dispensed\r\nAnd account reduced to $80<\/pre>\n
Domain Terms<\/h4>\n
Agreeing on domain terms is an important aspect of scenario creation.\u00a0 Domain terms often do not appear in the Values form.\u00a0 Explicit domain terms usually beat implicit domain terms and decreases misunderstanding of requirements.\u00a0 Here\u2019s an example of the explicit Domain Terms form:<\/p>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven customer has account balance of $100\r\nWhen requested withdrawal amount of $20 is made\r\nThen dispensed amount is $20\r\nAnd account balance is reduced to $80<\/pre>\n
An alternative way of making domain terms standout is to use a scenario outline, such as:<\/p>\n
Scenario Outline:\u00a0 Withdraw cash from ATM\r\nGiven customer with < Account Balance >\r\nWhen ATM request is < Withdrawal Amount>\r\nThen ATM response is <Dispensed Amount> and <New Account Balance>\u00a0\u00a0\r\nExamples:\r\n|Account Balance|Withdrawal Amount|Dispensed Amount|New Account Balance|\u00a0\r\n| $100\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $20\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $20\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0  | $80\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 |<\/pre>\n
The advantage of explicit domain terms is they can be used for naming attributes and parameters in the implementation.\u00a0\u00a0 This decreases the impedance between requirements and code which aids in maintenance.<\/p>\n
Table Values<\/h4>\n
Although the domain terms appear in the preceding form, the scenario could be re-written with tables to separate them out.\u00a0\u00a0 The Table Values form looks like:<\/p>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven customer with:\r\n| Account Balance |\r\n| 100 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0|\r\nWhen ATM request is:\u00a0\r\n| Withdrawal Amount |$20 |\r\nThen ATM response is:\u00a0\r\n| Dispensed Amount | Account Balance |\r\n| $20 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0| $80 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0|<\/pre>\n
Now the domain terms stand out \u2013 Account Balance, Withdrawal Amount, Dispensed Amount.\u00a0 The tables may be in either orientation. \u00a0\u00a0One convention is to use horizontal tables for Given\/Then and vertical tables for When.<\/p>\n
Often customers who have experience with using spreadsheets such as Excel find it easier to read the Table Values form over the Values form.<\/p>\n
One advantage of using tables is that they can easily be expanded for more terms without having to alter other aspects of the scenario. \u00a0\u00a0Here\u2019s a non-happy scenario:<\/p>\n
Scenario: Attempt withdrawal with insufficient funds.\r\nGiven customer with:\r\n| Account Balance |\r\n| $100 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0|\r\nWhen ATM request is:\u00a0\r\n| Withdrawal Amount |$120 |\r\nThen ATM response is:\u00a0\r\n| Dispensed Amount | Account Balance\u00a0\u00a0 | Message\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0|\r\n| $0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $120\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | Insufficient Funds |<\/pre>\n
Calculation:<\/h4>\n
This form gives variations of a calculation or business rule.\u00a0\u00a0 Calculation or business rule scenarios are different from flow scenarios.\u00a0 In a flow, such as withdrawing cash, the Given gives a necessary pre-condition such as an account with a balance.\u00a0\u00a0 A calculation or business rule does not require pre-conditions.\u00a0 It simply converts inputs to one or more outputs.<\/p>\n
Suppose there was a business rule that specified a transaction fee based on the withdrawal amount and the number of transactions on a day.\u00a0 Here are some examples \/ tests of the business rule with the input in the When:<\/p>\n
Scenario Outline:\u00a0 Determine Transaction Fee\r\nGiven ATM request is being processed\r\nWhen ATM request is < Withdrawal Amount> and < Number of Daily Transactions >\r\nThen ATM response is < Transaction Fee >\r\nExamples:\r\n| Withdrawal Amount|Number of Daily Transactions|Transaction Fee |\u00a0\r\n| $200\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | 2\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $2             |\r\n| $100 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0| 1\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0     |<\/pre>\n
Alternatively, the input could be shown in the Given, such as:<\/p>\n
Scenario Outline:\u00a0 Determine Transaction Fee\r\nGiven ATM request is < Withdrawal Amount> and < Number of Daily Transactions >\r\nWhen request is processed\r\nThen ATM response is < Transaction Fee >\r\nExamples:\r\n| Withdrawal Amount|Number of Daily Transactions|Transaction Fee |\u00a0\r\n| $200\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | 2\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $2             |\r\n| $100 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0| 1\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $0             |<\/pre>\n
A more compact form of a business rule could be:<\/p>\n
Scenario:\u00a0 Determine Transaction Fee Business Rule\r\nGiven inputs when fee computed then fee is\r\n| Withdrawal Amount|Number of Daily Transactions|Transaction Fee |\u00a0\r\n| $200\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | 2\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $2             |\r\n| $100 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0| 1\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | $0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 |<\/pre>\n
In either case, the domain terms for both the input and output of the business rule are explicitly specified.<\/p>\n
Chatty:<\/h4>\n
Scenario:\u00a0 Withdraw cash from ATM\r\nGiven I have $100 in my account\r\nWhen I access the ATM with my card\r\nAnd I select withdraw money\r\nAnd I enter $20 for the amount\r\nAnd I hit the enter button\r\nThen $20 comes out of the ATM\r\nAnd my account goes down to $80<\/pre>\n
This form describes every single action of a user interface.\u00a0\u00a0 If the exact steps of a user interaction are important, then this is a way of recording them.\u00a0\u00a0 However, for many people, this form is too chatty having many more words than necessary to document the scenario.<\/p>\n
Summary:<\/h4>\n
Six shades of Gherkin have been shown – outline, values, domain terms, table values, calculation, and chatty.\u00a0 For a particular scenario, the Gherkin is not fixed.\u00a0 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.\u00a0 Or you might start with a Chatty shade and cut it down to a Values shade.\u00a0\u00a0 The key is having the scenarios contain necessary and sufficient detail for everyone in the triad to have a clear understanding.<\/p>\n
 <\/p>\n
 <\/p>\n
 <\/p>\n
 <\/p>\n
 <\/p>\n
 <\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Introduction: A common format for scenarios is Given\/When\/Then.\u00a0\u00a0 The Gherkin language revolves around the Given\/When\/Then organization.\u00a0 Scenarios can be written in Gherkin in many variations, each of which has a different shade of meaning.\u00a0\u00a0\u00a0 These shades I\u2019ve denoted as outline, values, domain terms, table values, calculation, and chatty.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3,4,5,1],"tags":[],"class_list":["post-139","post","type-post","status-publish","format-standard","hentry","category-atdd","category-bdd","category-gherkin","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/posts\/139","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/comments?post=139"}],"version-history":[{"count":4,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/posts\/139\/revisions"}],"predecessor-version":[{"id":145,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/posts\/139\/revisions\/145"}],"wp:attachment":[{"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/media?parent=139"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/categories?post=139"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/kenpugh.com\/blog\/wp-json\/wp\/v2\/tags?post=139"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}