Writing Better Stories With Gherkin

Gherkin language was developed to write use-case stories in simple english. These days, it is widely used by test/QA professionals to write test-case scenarios. The beauty of Gherkin is it’s simplicity. Unlike tradtional test write-ups, Gherkin writeups are simple to understand and interesting to read. Notwithstanding the simplicity of Gherkin, here are three rules you could follow to improve your Gherkin scripts. It will not only make your scenarios simpler but also improve efficiency of your test process.

1. Write what you would tell

Before writing your scenarios in Gherkin, imagine you are sitting next to your friend. Whatever you would tell him to explain the scenario, is what you should try to put into writing. Lets look at the following web page.

Let’s say you want to explain a scenario that will verify the basic function of this page to your friend. You would probably tell something like the following to your friend -

`The scenario is to verify that google's 'create account' page is working fine. You have to enter all the necessary values submit the form. On submission, if you see a page asking for phone number, the test is a pass. Make sure that you enter valid values only.`

This is exactly what you need to write in Gherkin language. In Gherkin, it may look like the following.

Scenario: To verify Google account creation page

Given Google account creation page at url <url>

When user enters all necessary values including a valid password

And submits the page

Then the user should see a page asking for phone number.

Note that the Gherkin scenario is similar to your talk with your friend. This is an important benchmark you can use while writing or reviewing Gherkin write-ups.

2. Avoid jargons

Jargons are nobody’s friends. So, try to avoid jargons while writing scenarios. Let us look at an example.

enter the following string in the multi-line textbox for address and click the Next button.

This line has technical jargons like *string*, *multi-line textbox*, *button*. They may be common words within dev or QA community but they are not common english words. You could convey the same message with just common english words. 

type address and submit the page.

Avoiding jargon may look easy to follow but it’s probably the most difficult to implement.

3. Follow English grammar

Once you have written your Gherkin scenario, read it starting with the Given word. If the whole scenario reads like one english sentence, you are on the right track. Let us look at the following scenario :

Given the user login ok

When user enters account number in the textbox labelled 'User Name'

When user selects the paid user checkbox

When user clicks on the View button

Then user can verify account details on the page

It is obvious that the scenario is not a valid English sentence. The same scenario can be written as a valid English sentence.

Given that the user login is complete

When the user submits account number as paid user

Then the user should see account details.

Follow the rules and have fun writing Gherkin.