Capturing Examples using Gherkin

Capturing Examples using Gherkin

Modern software companies are realizing that there is no such thing as delivering a final product to the customer. Rather, companies are seeking to build a long-term relationship with the client and continuously deliver incremental value. The client is to be kept at the centre of what companies are delivering. 

Throughout my experience in the industry, I realized that even though we deliver functional products, we still get surprised clients during demo or delivery sessions. There are cases where assumptions are made, ending up with providing a solution to the client that differs from what was initially expected. Moreover, I still see developers struggling with understanding what the business actually agreed on with the client and what they are expected to develop and deliver. Most of the time this happens since people coming from business and techies speak a different language. The same term might mean different things for people coming from different backgrounds. Even though there is an effort to build requirements and gather what is required by the client, these same requirements become blurred as they are communicated down to the soldiers on the ground who are actually developing the product. Developers might be presented with lengthy documents which may be tedious to read and as time passes by, become stale and out of sync with any changing expectation of the client. 

Clearing the ambiguities

In this post, I am going to discuss an approach that can bridge the gap between people coming from different domains and who are ultimately all contributors to delivering value to the client. I am going to assume that a company has a level of established communication amongst the different stakeholders responsible to deliver something to the client. I am going to assume that the development team does not wake up one morning and decide they want to create a new cashout feature since they think this is what the client needs. The Product team understands the business domain and can perceive how their product can be used by the client. I have attended numerous meetings where requirements are discussed. The Product team explains what needs to be achieved to those who can design, implement and deliver an increment in the product. During these meetings, examples are given to explain rules, concepts or requirements. 

We might take an example which is not directly related to the tech industry. Let us say your lawyer friend tells you,

Writers should split their salary based on their contribution”.

Even though this seems to be a relatively simple rule, different people may interpret it differently. How is the contribution calculated? Is it based on the number of words, time or pages?

In order to clear this out, our friendly lawyer proceeds by giving us an example: 

“John, Peter and Mary wrote a 250-page book together. John and Peter wrote 100 pages each, therefore they each get 40% of the total earnings. Mary on the other hand wrote 50 pages. Therefore, Mary gets 20% since she wrote 50 pages.”

This simple example clears any doubt on how the rule works. This may be fairly easy to remember and refer to as time passes by. However, problems arise when there are more complex concepts which potentially require more complex examples to explain. Banking rules, such as how the daily interest is calculated on different types of bank accounts depending on their different states and allocated interests, might need a number of examples for one to understand. As good as these examples may be, they are likely to be lost in conversation if they are not recorded and referred to. The solution to this is to actually write these examples using a syntax and a language that is easily understandable by all parties. These examples can be captured using the Gherkin syntax. 

What is the Gherkin syntax?

 The Gherkin syntax can be defined as a business readable language which is used to express a system’s behaviour. The following is a very simple example written using the Gherkin syntax. 

Given the user loads the Google homepage

When the user searches for Cats images

Then results for Cats images are shown

As you can see, it does not use any special symbols or fancy text. It uses plain, simple English that everyone can understand.  This syntax is still bound to a number of rules and guidelines that are to be followed. The most commonly used structure attributed to Gherkin is the ‘Given, When, Then’ structure. These are not the only keywords used in this syntax. In future blog posts, I will be discussing how these keywords are used together with a number of guidelines to take into consideration when using such syntax. 

Gherkin enables us to write examples in a structured, yet fluent way. It brings business and technical stakeholders together and ensures they are understanding the same concepts and rules. It breaks down the silos of having separate teams working in isolation. No team simply works on a specific part and just throws it off the fence for other teams to capture and keep working on it. 

A practical example

Let us take a practical example of how Gherkin can be used to capture examples mentioned in a conversation. The business department might come up with an idea: 

In order to encourage new customers to use our food ordering app, food deliveries should be free of charge if the delivery location and the restaurant location are relatively close. 

This seems to be a straight forward requirement, however, as it is discussed by stakeholders, questions may be raised. 

Is there a minimum order amount for free delivery?

Is there a limit on the number of free deliveries a customer can get? 

What is a ‘relatively close’ location? Is it 1km, 2km? 

How is the closeness of locations calculated? Is the traffic to arrive at a destination taken into consideration?

These are valid questions that stir conversation and enhance the original given requirement. For example, it is concluded that the user has to make at least an order of €10 and is within a driving distance of not more than 15 minutes to be eligible for free delivery. The following are some of the examples written in the Gherkin syntax that can be created and used as reference by any stakeholder. 

Given the user makes a €10 order

And is within 15 minutes driving distance

When the user proceeds to checkout

Then the user is entitled to free delivery


Given the user makes a €5 order

And is within 15 minutes driving distance

When the user proceeds to checkout

Then the user is not entitled to free delivery


Given the user makes a €15 order

And is within 20 minutes driving distance

When the user proceeds to checkout

Then the user is not entitled to free delivery

It is important to mention that the aim of these examples written at this stage is to model the business rules. We are not after creating user journeys through a UI. When building such examples, it is important to be as declarative as possible. The specific interaction with UI elements is irrelevant. What we are after here is the outcome of the business rule or requirement we are describing. 

From Examples to Executable Specifications

This syntax forces everyone to use a pattern and a style that is common to all stakeholders. Even though this is a major advantage of using such syntax, a bigger advantage to using the Gherkin syntax is that it can be understood by tools such as Cucumber. Cucumber enables development teams to translate each step of these examples into a set of automated commands and transform these examples into executable specifications. This process takes the advantages of these examples to another level. Teams at different maturity levels take a manual approach at using the written examples to validate that what is being delivered is actually correct. However, automating these checks gives continuous guarantees to all the involved stakeholders, with the least human intervention possible. 

Using the Gherkin syntax to capture examples, each of which explains business rules and requirements, means that now, people coming from different domains, can use a language that they can both understand and they can both benefit from.  When creating these examples, the given requirements are questioned and challenged. These requirements are refined and any possible gaps are filled. Using tools like Cucumber, the created examples can become automated tests which can be used at any stage of the development and delivery process, confirming alignment to the customer value.  The following illustration shows how these three elements interact with each other.



Capturing the examples given during conversations using Gherkin and using them as automated checks throughout the whole process will not solve all the misalignment problems companies face. However, it tackles a major misalignment issue which can be a very common problem in growing software companies. 

Future posts will build on this one and delve deeper into standards and guidelines when using Gherkin. Moreover, they will focus on the very important point of having these examples serve as Living Documentation.  These examples should be accessible to anyone who wants to understand the key business rules for a specific requirement or deliverable. Not updating these examples results in simply another set of stale documentation, giving little to no value at all. 


Leave a Reply

Your email address will not be published. Required fields are marked *