How to describe user stories using Gherkin language

Definition of a user story

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

Benefits

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;

Formats of user stories

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 Globaldev company we use Gherkin language to make a user story more readable and understandable both for developers and clients.

Definition of Gherkin language

Gherkin is a human-readable language for system behavior 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 user stories start with a special keyword and consist of features and scenarios, for example:

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 the benefits that we’re going to get from this function.
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.

Implementation

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.

Conclusion

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 in more detail. 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