How to describe user stories using Gherkin language
OUR Blog
QA Engineer
Aleksei Stiagailo
QA Engineer
Jun 30 2016

How to describe user stories using Gherkin language


A user story is a description of functionality or part of functional written in the everyday or business language which captures what a user does or needs to do.

User stories provide rapid way of handling customer requirements instead of formal requirement documents and without performing administrative tasks related to their maintenance.


common image

Specialists of our company formulated benefits of using user stories for each member of Agile’s team:

For Project Managers:

  • It helps to make the application architecture correctly;
  • It reduces time of answering questions about the logic of the application to developers, designers, testers;
  • It can be used as documentation and updated easily;

For Designers:

  • It gives insight into the amount of mock ups needed to cover the entire layout application;
  • It warns of excess or missing certain screens / buttons / features;

For Developers:

  • Features are the basis for writing acceptance tests with test-driven development (TDD and BDD);
  • It helps avoid misunderstandings of documentation (specifications and requirements of the customer), and errors in the logic of the application;

For QA:

  • It serves as the basis for writing test cases and test scenarios;
  • It helps quickly understand the logic of the application;

For clients:

  • Gives good understanding of an application and how it works;
  • The client can describe the new functionality, using our user Story format that prevents misinterpretation of requirements;


Also you can meet the following formats of a user story:

Mike Cohn, a well-known author of user stories, regarding the "so that" clause as optional:

"As a <role>, I want <goal/desire>"

Chris Matts suggested that "hunting the value" was the first step in successfully delivering software, and proposed this alternative as part of Feature Injection:

"In order to <receive benefit> as a <role>, I want <goal/desire>"

Other options:

"As a <role>, I want <goal/desire> so that <benefit>"

"As a <role>, I can <action with system> so that <external benefit>"

In the Steelkiwi company we use Gherkin language to make a user story more readable and understandable both for developers and clients.


Gherkin is a human-readable language for system behaviour description, which uses indentation to define the structure of the document (spaces or tabs). Each line starts with one of the keywords and describes one of the steps.

Most lines in the Gherkin start with a special keyword and consist of features and scenarios, for example:

start lines in the Gherkin

Let’s look through the above example:

1. Feature: A short but comprehensive description of the required functionality, which starts a function and gives it a name.

2. Next three lines describe benefit that we’re going to get from this functional.

3. Scenario: Some specific business situation starts the script and contains a description.

4. The following 7 lines describe the test steps, which correspond to specific code, performing the described action. The lines that are followed by the keywords "Given", "AND", "Then", etc. are compared.


common image2

Below, you can see how the initial part of one of our user stories looks like:

User actions: In order to view photos, set likes, view news, upload photos and take part in contests As a user I want to download application from App Store, then register/login, then search photos by artist, view photos, set likes, view news, upload my photo, add photo in contests.

1.1. Registration: In order to Sign up As an unauthorized user I want to open a downloaded application, then click “Sign Up” button, fill in all mandatory fields (email, password, etc), connect to Google+/Facebook/Instagram/Twitter and add friends who are registered in PhotoCulture application, then redirect to Home page.

1.1.1. Download application: In order to Download application from App Store As a user I want to open App Store, then click search button, then input “____”, then click “Install” button.

1.1.2. Sign Up: In order to Sign Up As an unauthorized user I want to open a downloaded application, then click “Sign Up” button, then redirect to “Sign Up” screen, then input correct value in “email” field, input correct value in “password” field, duplicate password value in “confirm password” field, then click “Sign Up” button, then display “Check your email to complete registration” pop up, then confirm registration in my email.


Before writing an individual user story, we create the story that describes end-to-end scenario of application behavior from registration to completion of the application (logout). In this user story, we describe all the actions which the application is created for, for example, viewing photos of other members by adding your own photos, participation in competitions, receiving awards, writing comments, etc. Below, we make individual user stories that describe certain functionality more detailed. Further, if necessary, we describe the more detailed parts of the previous user story.

A distinctive feature of our company is that our user story isn’t separated from the general structure of the project. We form all user stories from application in a single document in which they appear in the treeview structure.

Advantages of our approach

  • It helps avoid non-compatible user stories with the application architecture
  • It shows how the changes affect the application structure
  • It enables customers to make new requirements and wishes more understandable for developers


  1. User story
  2. Writing features - gherkin
Oct 24 2016
Let’s speak about video blogging! We will tell you how much it cost to develop a Vine clone and about other successful apps for video editing.
Oct 14 2016
“Why do I need Product requirements document if I just want to analogue application or this site???” is the most frequently asked question. So let’s look closer at the reasons why we need this document and what should it contain.
Oct 12 2016
To create a high-quality product developers need a document describing all the requirements. In given article we talk about the types of requirements and why they are so essential today.