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.
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:
- Scenario (can also be called Example)
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 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...
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 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
The When keyword represents an action. For example:
- When I press the “logout” button
- When I donate 5 Euro
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
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...
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.
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.
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).
Chrome application. Can be downloaded here.
See image below. You type in top panel, and Tidy Gherkin will output formatted Gherkin in bottom panel.
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.