Improve your User Stories with Gherkin: Given, When, Then

Do you need to improve communication between Business and Tech? Use Gherkin to write your acceptance criteria.

User story, please meet Gherkin

When teams are introduced to the use of Gherkin for writing user stories, reactions range from enthusiasm ( “Cool!”) to a bit of suspicion (“Are they questioning how I write my tests?”) but the general acceptance is high, and usually even higher after few days into using it.

After using Gherkin, user stories are now getting much more focused, short and understandable, on both product and technical sides. Conversations about stories during refinement meetings are shorter and better framed.

By the way, what is Gherkin

Gherkin is a very simple english-like language, that you can use to describe requirements or acceptance criteria. The main basic format is as follow:

Gherkin can be used and understood by non technical roles like product owner or business analyst, but gives enough structure to be used by devs and QAs as a basis for automated testing and living documentation. It improves communications between business and technical roles. What to build is much better understood, and how to build it is much better focused.

So, how does it work? First describe the feature to be implemented, usually in the classic form of a user story:

AS a <persona>, I WANT <feature> , for <Business Value>.

Then you can describe one or more business scenarios, meaning the overall behavior you want to obtain with the user story.

  • Scenario. For instance, you can describe a scenario like that: “The Visa Cardholder use the Visa Classic for paying”
  • Given. Use the given keyword to describe the context for a business behavior. For instance: “I am a Visa Classic Cardholder “
  • When. Describes the action required in order to produce the output, i.e. “I pay with my Visa Classic”
  • Then. Describes the expected output, i.e. “My Visa is accepted”
Feature: Payments with Visa Classic
As a Visa Classic Cardholder, 
I want to use my Visa Card, 
For paying my purchases.

Scenario: The Visa Cardholder use the Visa Classic for paying
    Given I am a Visa Classic Cardholder
    When I pay with my Visa Classic
    Then My Visa card is accepted

Multiple conditions can be concatenated with the AND keyword. For instance:

Given I am a Miles&More Fidelity Card holder,
And I Am a Premium Bank Customer 
When I transfer money to my account
Then I also receive 100 points on my Miles&More Card

Multiple scenarios for a single feature are allowed, they can be expressed in a more concisely format with Scenario Outlines and data tables, for instance:

# Two scenarios for the same feature

Feature: Bank account calculation 
As A bank customer,
I want the balance of my account correctly calculated
To be certain of my financial sistuation

  Scenario: 1) bank account in-flow calculation
    Given the starting balance has 4000 Euro
    When 3000 euros are added to the account
    Then the final balance is 7000 euro     


  Scenario: 2) bank account out-flow calculation
    Given the starting balance has 4000 Euro
    When 3000 euros are transferred to another account
    Then the final balance is 1000 euro    

# Here we use a scenario outline to include the 
# two previous scenarios into a single one

Scenario Outline: bank account cash flow calculations
  Given the starting balance has <start> euros
  When <amount> is trasferred
  Then I should have <left> euros
    | start   | trasferred | left |
    | 4000    | +3000      | 7000 |
    | 4000    | -3000      | 1000 |

Test Automation – The Next Step

Once you got used to have requirements and user stories written in Gherkin, the next step is to transform them in test cases, automatically executed at every deploy. There are a number of frameworks, from Cucumber to Behave, that can be used to automate your Gerkin acceptance criteria. These second step will be much easier if you are already used using Gherkin as a communication tool.

So as simple as that, the Gerkin approach helps your product owner better communicate with devs and specialists about what to do . The IT professional will acquire better domain-related competences and customers representatives will better explain what they want to achieve. These way you will be prepared to further increase the quality of your delivery with automated acceptance criteria.


Marcello Del Bono is coaching and leading Agile Teams, supporting Transformation programs. He has multi-year experience as a Product Owner, Scrum Master and Agile Coach in e-commerce, IT, Marketing and Decision Support Systems in Media, Telco, Finance, Fashion industries.

Contact him on LinkedIn.