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.

common gherkin mistakes

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.


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.


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.


Given the user is on ""
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


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.


Given the user navigates to ""
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


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?
Cucumber and Gherkin are incredibly useful when you learn to use them in a reliable way. We love this dynamic duo which is why we’ve written a guide on Cucumber and Gherkin that you should read.

Now that you are on your way to mastering Gherkin features, learn how to set up and run your Cucumber and Selenium web tests on GitLab and how work more efficiently with test automation by using Calliope Pro. Calliope was designed not only as a test results dashboard to share and compare aggregate test results  with the rest of the development team (independent of tool or framework), but it also allows you to a schedule and run test results on demand.

Thanks for reading!
Gijs Pauldies, Test Automation Engineer


Suggested Posts

Written by: spriteCloud

This is the spriteCloud company author. We use this profile when posting general company-related things and as a catch-all for posts that were written by former colleagues.