Gherkin Syntax

We need to capture requirements in a clear and consistent manner.  We will be using Gherkin syntax for doing this.  Gherkin syntax provides a structured way to writing requirements for new features.

The Syntax

Gherkin is very easy to pick up.  It has a few key words that for the most part are self explanatory.  These key words are:

• Feature
• Background
• Scenario (can also be called Example)
• Given
• When
• Then
• And

Feature

Feature is a required keyword.  It is always the first keyword to be used in a Gherkin document.  You need to give the Feature a name, followed by a description.

The description is used to give an overview of the feature.  This could be a description of the business logic, a new button on a UI, etc.

The format is as follows:

Feature: Write blog about Gherkin syntax
description...

The description of a Feature is considered finished when you encounter the next keyword, for example Background, or Scenarios. So make sure your description does not start with a keyword.

Background

Background is an optional keyword. Only use it if you need it. Background gives  extra context to the scenarios. Use the Background to avoid repeating information in the Scenarios.  For example, Given I am logged in as a particular user, or Given this data is in the database. Do not make the background too long or too complex. Use the Given and And keywords for setting up the background.

The format is as follows:

Background: 
Given I am logged in as a manager
And the following data exists in the database...

Scenario (Example)

Scenarios describe the logic of the Feature. They explain what the Feature does, and what it expects as a result. This includes happy paths and error handling. Each Scenario must be represented by Unit/Integration test in your code.

Scenarios use the Given, When, Then keywords for explaining the logic. I will explain these keywords now before giving a full example of a Scenario.

Given

Given sets the initial context of the Scenario. For example:

• Given I am logged in as John Doe
• Given I have 10 Euro in my account

When

The When keyword represents an action. For example:

• When I press the “logout” button
• When I donate 5 Euro

Then

The Then keyword is the result of the action. For example:

• Then I will be logged out
• Then I will have 5 Euro in my account

And

The And keyword is applicable to any of Given, When, and Then keywords. Use it to append extra criteria. For example:

Given...
And...
When...
And...
Then...
And...

Full Example

Scenario: Transfer funds from account
Given I have 10 Euro in my account
When I transfer 4 Euro
Then I will have 6 Euro in my account

Scenario: Transfer funds with insufficient funds
Give I have 2 Euro in my account
When I transfer 4 Euro
Then I will get an error saying "Insufficient funds"

Keep it Simple

The idea is the syntax should be clean and concise. Do not write essays.

Backgrounds and Scenarios should be no longer than 5 or 6 lines. Anything more than this is a smell.

Do not spoon feed your reader in the scenarios. This makes for long scenarios that become tedious to read. Assume the reader will know enough from the feature and background. For example, never write something like the following:

Scenario: Transfer funds from account
Given I log in as John Doe
And I click on the menu button
And I select to navigate to Transfer-Funds page
When I click in the amount text box
And I enter 4 Euro
And I press Transfer
Then I will see a success message
And I will have 6 Euro in my account
And you need help if you are still reading this

This is awful to read. Most people will have given up or start skipping over sentences. Especially considering you could have several scenarios in the same area.  Are they all going to tell the user how to navigate to the page?  Keep it simple as per the examples in the previous section.

Editors

I found Jira particularly tedious for writing Gherkin documents. It has no syntax highlighting or formatting. The following are a couple of editors I found useful.  I would write my feature in the editor, and copy the formatted output to Jira.

Intellij

Just create a file of type feature, e.g. example.feature. Intellij will automatically identify it as Gherkin syntax. Use ctrl+alt+L to format (assuming you’re using default Intellij keyboard commands).

Tidy Gherkin

Chrome application. Can be downloaded here.

See image below. You type in top panel, and Tidy Gherkin will output formatted Gherkin in bottom panel.

What’s Next

For now we are manually writing these features.  However, the ultimate goal is that this will be integrated with the BPMN process.  This means that our Jiras can be automatically created from BPMN.  The Jiras will be fully documented with Scenarios that are mapped out in the BPMN diagrams.