Six Shades of Gherkin

2021-07-07 21-07-07
Gherkin
by Ken Pugh

Share!

 

There are many ways one can write Gherkin in a feature file. To illustrate several shades of Gherkin for the same functionality, I’ll use the example included in the download of SpecFlow.  

Feature: Calculator
    In order to avoid silly mistakes
    As a math idiot
    I want to be told the sum of two numbers

@mytag
Scenario: Add two numbers                  # shade 1
    Given the first number is 50
    And the second number is 70
    When the two numbers are added
    Then the result should be 120

When two different numbers are added, a beginning user might copy and paste this scenario and replace the values.

Scenario: Add two numbers with one negative # shade 1
    Given the first number is -1
    And the second number is 70
    When the two numbers are added
    Then the result should be 69

After the user learns about Scenario Outline, then these scenarios might be combined into an Example Table and look like shade #2

Scenario Outline: Add two numbers # shade 2
    Given the first number is <first number>
    And the second number is <second number>
    When the two numbers are added
    Then the result should be <result>
    Examples:
    |first number | second number | result   |
    | 50          | 70            | 120      |
    | -1          | 70            | 69       |  

With just values in the table, it can be sometimes unclear as to why the values were chosen. You can add a notes column that gives an explanation, such as shade #3.  The notes column does not need to be referenced in the scenario, although you could pass it to a step definition if you wanted to print the value in a message.

Scenario Outline: Add two numbers # shade 3 
    Given the first number is <first number>
    And the second number is <second number>
    When the two numbers are added
    Then the result should be <result>
    Examples:
    |first number | second number | result   | notes                   |  
    | 50          | 70            | 120      | adding positive numbers | 
    | -1          | 70            | 69       | adding negative number  |
    | 50          | 999999949     | 099999999 | result is maximum allowed |

Depending on the number of cases, you can break down the examples table into multiple ones. One could represent the standard cases, the other could represent edge cases.  

Scenario Outline: Add two numbers # shade 4
    Given the first number is <first number>
    And the second number is <second number>
    When the two numbers are added
    Then the result should be <result>
    Examples: Standard
    |first number | second number | result    | notes                   |  
    | 50          | 70            | 120       | adding positive numbers | 
    | -1          | 70            | 69        | adding negative number  |
    Examples: Edge cases 
    |first number | second number | result    | notes                   |  
    | 50          | 999999949     | 099999999 | result is maximum allowed |

The Scenario Outline is a common sight. You might observe that running this outline requires 12 step definition calls.  (4 for each scenario times 3 executions of the scenario). Sometimes the Given/When/Then starts looking like boilerplate, e.g.  “first number is <first number>,  second number is <second number>”.

There is an alternative (shade 5). You can use a step table that looks exactly like the Examples table. You only need one step definition. The method receives a table that is converted into a list of objects and then loops through that list.   

Scenario: Add two numbers #shade 5
    * Add first number and second number to give result 
    |first number | second number | result    | notes                     |
    | 50          | 70            | 120       | adding positive numbers   | 
    | -1          | 70            | 69        | adding negative number    |
    | 50          | 599999949     | 599999999 | result is maximum allowed |

The test output will only show one test, regardless of the number of table entries. This decreases the output that has to be read.      

Another way of writing this scenario is using a custom preprocessor. The preprocessor inserts an external files (e.g. CSV, XML, JSON) content into the feature file before it is interpreted by SpecFlow. In this case the feature file may look like this:

Scenario: Add two numbers #shade 6
    * Add first number and second number to give result 
    #include “addition.csv”

The addition.csv file can be created with a text editor or using a spreadsheet program and saving the data as a .csv file. It contains the following:


    first number, second number, result, notes
    50, 70, 120, adding positive numbers 
    -1, 70, 69, adding negative number
    50, 599999949, 599999999, result is maximum allowed

When the feature file is pre-processed, the output and test results will look like shade 5. 

Summary:

Six shades of Gherkin were presented. There are more shades you may see in articles and books. Don’t stop at one, but take a look at others to see if another shade works better for you and your team members.    

Make sure to check out the Given When Then With Style Challenge to hone your skills for writing better feature specifications.