What is Gherkin?

Gherkin is a universal language that easily understand by all people on the team. It is actually describe the business value of an app, and it is user oriented document. This language format, or syntax, is also known as a BDD (Behavior Driven Development) Specs.

Why we need it?

There are some reason why we need a Gherkin Language. Here as some benefits :

Apps are made usually from a bunch of people working together. Usually, the people in the team have different roles. There are business, design, mobile, web, QA team, etc. basically, they have different roles. That is why, in order to have the same picture of a feature, a unified general language that understandable by the team is required. This is why we need a common language, the Gherkin.

After the Gherkin created, it can be passed to the more technical document, the Use Case based document. The Gherkin Language can be mapped to a Use Case document that represent the Story, Acceptance Criteria, and failure cases with more detail knowledge of technical keywords, like error, validates, return, map, execute, with ordered steps, to represent the communication between the components in the codebase. And, this documents can also be mapped to an object on the codebase, so that it can be reused or at least, represent a feature that user needed on the codebase.

Another example why we need to use a Gherkin Language is for UI Testing, or User Acceptance Testing. After developing a feature, the team needs to test the app. The app is tested based on the user centric way of using the app, the behavior. Without a well documented user centric scenarios, the test will not be able to replicate the expected app behavior.

When to define it?

It is always better to take time, step back, and thinking for a little while to create the BDD Specs with the Gherkin Language, then moved to a use case document. Because, at the moment, the feature are being discussed among the team, and actually minimizing the miscommunication between people in the team, or even with the user. So, it is actually best to create this when the project or a feature started.

Where should I put it?

When I code for my own project, I usually put the Gherkin Language as closest as possible to the project. In my case, I put that on the file on the project. This document becomes my starting point to understand the project, focused on the functionality, and become the reference steps to implement the tests.

How is the document looks like?

Where is how I usually implement the Gherkin, or the BDD specs. I usually put this on my

Story: Customer requests to see their transactions

Narrative #1

As an offline iOS user,
I want to be able to load my transactions immediately,
so that I can see my transactions

Scenarios (Acceptance criteria)

Given the customer does not have connectivity
 And there’s a cached version of the transactions
When the customer requests to see their transactions
Then the app should display the latest transactions from local

Given the customer does not have connectivity
 And the cache is empty
When the customer requests to see their transactions
Then the app should display empty transactions

From this document, all team should be able to easily understand the value of the app.


Gherkin Language is one of important document that we developer, or team, need to have. With this format / syntax, everyone on the team or user can have the exact same picture of a feature. So, from this, it can be derived to another documents, like Use Case Specs that I am going to publish on the next article.

References :

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s