Given-When-Then

Given-When-Then (also known as Gherkin) is a format for business-oriented acceptance tests and executable specifications.

It allows teams to express expectations (typically about deterministic discrete functionality) in a format readable by various roles (testers, developers, analysts and stakeholders) but also easy to verify through automated testing.

Example

Feature: End of year bonus calculations
 The company provides employees with end-of-year bonuses 
 based on their level and base salary. 

  Scenario: Bonus Calculation For Managers
    Given an employee of the Manager level
    And a salary of 75000
    When the end of year bonus is paid
    Then the employee should receive a bonus of 20000

  Scenario: Interns do not get bonuses
    Given an employee of the Intern level
    When the end of year bonus is paid
    Then the employee should not receive a bonud

A popular extension to this format allows for placeholders and tabular set of examples, reducing common text for related examples:

  Scenario Outline: Bonus Calculation 
    Given an employee of the <level> level
    And a salary of <salary>
    When the end of year bonus is paid
    Then the employee should receive a bonus of <bonus>
 	
 	Examples:

      | level   | salary | bonus |
      | Manager | 75000  | 20000 |
      | Intern  | 5000   | 0     |
      | Lab rat | 10000  | 1000  |

History

The wording “Given-When-Then” was originally proposed Chris Matts in 2004, as he, Liz Keogh, Dan North were then defining what would later become known as Behaviour-Driven Development. The format was initially adopted as part of the JBehave tool, developed by Keogh. Dave Astels then adopted it for RSpec. Aslak Hellesøy developed Cucumber, a Ruby testing tool evolving from the RSpec Story Runner, in 2009. Cucumber became widely popular in early 2010s, spawning numerous clones in various programming languages, helping Given-When-Then become the dominant pattern for describing executable specifications by 2020.

Extending the format to cover groups of examples and a hierarchical structure from “Features” and “Scenarios” to individual examples for the Cucumber tool, Hellesøy and other Cucumber contributors promoted the name “Gherkin” for the specific file format containing Given-When-Then specifications. Files containing Gherkin specifications customarily used the .feature extension, so they also became popular under the name “Feature Files”.

Patterns

The Given When Then With Style series of articles is available (republished from the original with author’s permission) on this web site, containing useful patterns, tips and tricks for writing specifications and tests in the Given-When-Then format.

Learn more about the Given-When-Then