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.

User Story e criteri di accettazione. Given, When, Then

Vuoi migliorare la comunicazione tra IT e Business? Usa Gherkin per scrivere i requisiti e i criteri di accettazione.

User story, ti presento Gherkin

La reazione del team quando si propone l’uso di Gherkin, può variare dall’entusiasmo al sospetto (stanno mettendo in dubbio i miei test?), alla preoccupazione (sarò in grado di farlo?) ma l’approccio in generale piace, e l’accettazione aumenta dopo qualche settimana di utilizzo.

Le user story diventano infatti più focalizzate, più brevi e comprensibilli sia dal punto di vista dello sviluppo che da quello del business. le conversazioni durante le sessioni di planning e refinement sono più strutturate ed efficaci.

Ma cos’è Gherkin?

Gherkin è un linguaggio english-like molto semplice, che può essere utilizzato per descrivere requisiti, criteri di accettazione, eventi e comportamenti. La struttura di base è la seguente:

Gherkin è un linguaggio che può essere usato e compreso anche da ruoli non IT come il product owner o il business analyst, ma è abbastanza strutturato per essere usato da tester e sviluppatori come base per comprendere i requisiti e automatizzare i test. Gherkin migliora la comunicazione tra ruoli business e IT, dando maggiore chiarezza e focus al cosa dev’essere sviluppato

Come funziona? Si comincia descrivendo la feature o il prodotto da sviluppare, idealmente in forma di user story:

COME <persona>, VOGLIO <feature> ,PER <valore di business>

La storia viene quindi focalizzata con uno o più scenari, ad indicare il comportamento complessivo che si vuole descrivere.

  • Scenario. Uno scenario può essere descritto come segue: “Il proprietario di Carta Visa Classic usa la carta per il pagamento”
  • Given. La keyword given descrive il contesto di un comportamento di business del cliente o dell’applicazione. Per esempio “Sono un proprietario di Visa Classic”
  • When. Descrive l’azione richiesta per produrre l’output descritto. Ad esempio “pago con la mia carta Visa Classic”
  • Then. descrive l’output atteso: “La mia carta Visa Classic viene accettata”
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

Condizioni multiple possono essere concatenate con la parola AND. Ad esempio:

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

E’ possibile gestire scenari multipli, oppure accorparli in un formato specifico usando gli Outline e le Data Table:

# 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 – Il prossimo passo

Una volta che ci siamo abituati a descrivere i requisiti e le user story in Gherkin, il passo successivo è trasformarli in test case, da eseguire automaticamente ad ogni deploy. Ci sono diversi framework che supportano questo tipo di automazione: Cucumber, Behave, pytest-bdd etc.

Con la sua semplicità, Gherkin aiuta i product owner a specificare i desiderata in termini strutturati, coerenti, facilmente comunicabili e facilmente automatizzabili per consentire, in definitiva, una maggior qualità dei delivery e del valore di business creato.


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.