Make your Gherkin Specifications More Readable

This article was written by Sophie Keiblinger. Sophie has been a software test engineer at TechTalk since 2014 and is based in Vienna, Austria. She is passionate about BDD and test automation because it “encourages and fosters communication between all stakeholders and leaves more time for exploring and finding the interesting stuff”.

Developers have coding guidelines and formatting tools that help them keep their code clean, maintainable and readable as well as increase recognisability. You might think that Gherkin has no need for such conventions, given that Gherkin is essentially written using a natural language. But giving your brain easily recognizable and expected patterns to work with makes reading feature files and working with Gherkin much faster and easier.

We have been asked if there are general conventions for Gherkin that should be followed. While there are none that we are aware of, we can share the guidelines that we generally agree on in our projects at TechTalk.

Discernible Given-When-Then Blocks

In theory, your scenarios can be as simple as a single Given, When Then step each. However, in real life, they tend to grow and have multiple steps for each of these keywords. In order to quickly spot where one block ends and another one begins, you can indent the steps starting with “And”. Then your scenario would look something like this:

Now, the steps in this example don’t use tables. If you use a lot of tables, you might find the visible pattern unruly or uneasy for the eye:

An alternative is to have every step start with the same indentation, and add an extra newline before the next keyword block. However, this makes your scenario longer, which is something you generally want to avoid – you don’t want to have to scroll in order to see all the information for a scenario. Plus, I personally prefer to use extra newlines differently (but more on that later).

In the end, it is probably best to decide with your team what is more important to you and which version you prefer.

Steps with Tables

We often use tables in our steps. In order to make it immediately recognizable that a step needs further input from a table, we use a colon at the end of the step. This helps when using Intellisense, which does not include table previews but will display the colon:

You can also formulate your step to make this clearer:

Notice that I used “following” in my step’s wording. I can only recommend this approach as well. However, in most of my projects, I can be sure that a colon at the end of the step means it is followed by a table. Indenting the table also makes it clear that it is part of that particular step.

Reducing Noise

In order to reduce noise, we recommend using default values for fields that the system requires, but that are not relevant to your scenario. For example, if you want to test the validation of a date of birth, you don’t need to know the person’s name, academic title or social security number. These might be mandatory fields in your application, but have no bearing on the outcome of your scenario.

This also works with steps that have tables, in which case you only include the columns needed for your scenario.

Parameters in Steps

As you can see in the example above, I used single quotation marks around step parameters. This makes it easy to spot parameters in a step, even with just very simple syntax highlighting or none at all.

Newlines within Scenarios

Using newlines helps your brain group the right information together and makes it easier to tell where the next logical unit starts. While the text may still be readable without newlines between steps/blocks when they are short, it becomes very difficult to read once tables are involved.

If your scenario starts getting long, newlines before each block might help to make it more readable. In the case of steps containing tables, I would always add newlines between each step:

I would also recommend adding a newline before your examples block:

Newlines between scenarios and separator comments

The more scenarios you have in the same file and the bigger they are, the harder it becomes to find the point where one scenario ends and another one starts. As a visual aid, we add 2 newlines between scenarios. Usually we also add a comment separator:

If you place the separator comment directly above your scenario (or its tag), they will be displayed when all scenarios are collapsed (including 2 newlines):

If you instead add a newline between the separator and scenario (or it’s tag), then you will see the scenarios neatly stacked after each other when they are collapsed (with 1 newline separating them):

All of these formatting conventions are ones that we generally agree upon in our projects. But remember that they are all just suggestions and approaches that we have developed over time to deal with various issues we have faced. It’s important to figure out what works best for you based on our own set of challenges and needs. So rather than seeing these formatting conventions as set in stone, try to use them to inspire you to find ways to make your own feature files more readable and easier to work with. And feel free to share any tips you may have!

I am sure that no matter what conventions you agree upon with your team, they will make working with and maintaining your Gherkin specifications easier.

All of the examples above can also be found on GitHub here.