The 3 most common mistakes writing Gherkin features

In the past, I’ve worked on many projects where they either used Gherkin to describe functionality or to be used for test automation. However, my time in working on projects were we used Gherkin, I’ve notice three common Gherkin mistakes I see over and over again.  You can have a look at how to write Gherkin scripts with a straightforward example if you need a primer on the topic.

The following recommendations are useful for both usages.

1. Writing scripts in first person instead of third person

When starting with Gherkin, people quickly feel like they should describe the actions they are performing when going through a functionality.

Wrong

Given I am logged in
When I delete a post on the blog
Then I should see a successful deleted message


The problem with the case above is that it’s not clear who this “I” person is. Is it an administrator, a moderator or a member? This is quite important information when reading Gherkin, so you can understand it quicker. This post goes more in-depth about why third person is better.

Right

Given the administrator is logged in
When the user deletes a post on the blog
Then a successful deleted message should display


2. Describing every action instead of a functionality

When writing Gherkin, it’s often seen as if you have to describe every action to get to the next step: Every click, every text input, web-page. But Gherkin is meant to describe a specific flow you’re going through.

Wrong

Given the user is on "http://training-page.testautomation.info/"
When the user fills in "test" for username
And the user fills in "test" for password
And the user clicks on the login button
And the user clicks on the logout button
Then the user should be on the login page
And the avatar should not display in the right top

Right

Given the test user is logged in on the training page
When the user logs out
Then the login page should display as expected


When this scenario is used in functional testing, someone reading it will understand what is suppose to happen.

For test automation, all the different clicks can be solved on a code level. Also, with a more functional description, it’s easier to group the code and repeat yourself less.

3. Using absolute values instead of configurable values

When writing Gherkin scripts, it’s always quick and easy to simply use the absolute values that you want to use. For example a username and password, or the values used in a registration form.

It’s best to practise to move your absolute values to a configuration file so you can set user information in a central place.

Wrong

Given the user navigates to "http://training-page.testautomation.info/"
When the user fills in "test" for "#login-username"
And the user fills in "test" for "#login-password"
And the user clicks on button "submit"
Then the page should display in logged in state

Right

Given "test-user" navigates to page "landing-page"
When the user logs in
Then the page should display in logged in state


So, in this case, the URL is moved into a configuration value called “landing-page” and the user credentials in “test-user”. If at any point in the future one of these values change, you’ll only have to change one configuration value with it.

Final word

When writing Gherkin scenarios, ask yourself the following:

• What is the goal of my scenario?
• Is my scenario descriptive?
• Can I use fewer steps to describe it?