Speak Gherkin And Learn How To Collect Requirements For Your Project

Collecting requirements for a project is a complicated process. If you don’t do it right, you can waste both money and time. Customers who start working with software development company often have problems with specifying their needs. To avoid communication failure when getting on a project — no matter if you are a customer or a contractor — learn how to collect the requirements!

Requirements Engineering Analysis

Defining the business problem — this is the first step of the Requirements Engineering Analysis. In this task, we should not focus on the details but rather think about the problem globally. Here is an example of a well-posed problem:

“It is becoming increasingly difficult to find qualified specialists for the ICT sector”

The second step is to create a solution to this problem. It can be a service, a product or even a process. Following on, the example of a solution for the problem posed earlier could be:

“Creating SkillHunt.io application — a recruitment platform allowing its users to get a high reward for referring a job to his or her friend”

At this stage, the details are needless. If we evaluate the idea, conduct market research and it turns out that our solution has a business justification, we can start collecting the requirements. To make sure they fulfill their function, we should check if they meet the 3 main criteria. They need to be:

  • Explicit and unambiguous
  • Understandable for all the stakeholders,
  • Up-to-date and documented.

To make the process of collecting requirements easier and to meet all the presented criteria, we can use the Gherkin language. It is a natural language which can be useful both to business analysts collecting the requirements and to developers creating the scenarios for functional tests.

Speak Gherkin fluently

The record of requirements in Gherkin is unambiguous, explicit, and — what’s most important — easy to understand for all the parties involved. Because of that, the discussion about the requirements is actually possible.

Just like every other language, Gherkin has its syntax. It has some specific structure, some keywords have to appear. Here is how it looks:

Feature: Logout from application
Given I am logged in
When I click “log out” button
Then I am informed about successful logout
And I am redirected to login page

The requirements collected in Gherkin are saved to a .feature file. Thanks to that, the developers can easily use these files for writing automated tests in BDD (Behavior-driven development) using Cucumber.

When we want to create a new requirements description, we need to define the Feature which gives us the name of a new functionality. Then, we go ahead with writing the Scenario. It’s worth to mention that one file can contain more than one scenario. Each scenario consists of three main steps: Given, When, and Then. The description following the word Given sets the preconditions, When defines the actions that take place at the particular functionality and Then describes the expected outcome of the action. In the example presented above, there is one more keyword: And which continues the method that it follows. Therefore, when listed after When, it would continue this section and define another action. Gherkin knows one more keyword: But — but, to be honest, in my whole career as a Project Manager, I have never found a situation when it could be applied.

Becoming fluent

Take a look at the example in which the user is logged in in each of the scenarios:

Feature: Select profile
Given I am logged in
Scenario: First profile select 
Given I go to application after logging
When I am asked which profile I would like to choose from my list
And I select profile from list
Then I see dashboard for this profile
Scenario: Next profile select
Given I am on dashboard
And I have selected profile
When I select from dropdown with list
Then I see dashboard for this

Moreover, if we want to discuss the requirements and, in the future, test more than one scenario, it is worth to use some examples — using the Example function. Collecting data in this form is often the most unambiguous. To use Example, we need to put the variable inside angle brackets <> and put the tables below the scenario. We need to remember that if we use examples, our scenarios should be named Scenario Outline. The following example should make it clear:

Feature: Login to application
Given I am registered user
And my account is activated
Scenario Outline: Successful login
Given I am on login page
When I fill "login" with <login>
And I fill "password" with <correct-password>
And I click "Login" button
Then I am redirected to page with profile select
| login | correct-password |
| Lukasz | Gh3rk1n |
| Arek | Cucumb3r |
Scenario Outline: Unsuccessful login
Given I am on login page
When I fill "login" with <login>
And I fill "password" with <incorrect-password>
And click "Login" button
Then I am be informed about unsuccessful login
| login | incorrect-password |
| Lukasz | Gherkin |
| Arek | Cucumber |
Scenario: Unauthorized entry
Given I am not logged in
When I try to go Dashboard page
Then I am redirected to login page

Of course, in agile projects, the requirements are changing. It is necessary to apply changes in the .feature files and therefore — the on-going changes in application tests. This way we can keep our documentation up-to-date. Completing the tasks in compliance with the scenarios results in delivering up and running elements that perfectly fit with the principles of the Agile management.


Originally published by Łukasz Nowacki at neoteric.eu/blog on October 20th, 2016.