5 Mistakes you need to stop while writing cucumber features

BDD is a persona-based product development methodology. BDD always encourages the development team to identify how real users (human) would interact with the system. BDD is really helpful to provide a common vision to the team. Product owners basically narrow down the business needs to a human-readable language, called Gherkin. This is a plain English format where every acceptance criteria (behavior) is defined by a set of keywords, Give-When-Then.

So, That sounds fun and easy. But, in large-scaled teams, it’s always a challenge to maintain Gherkin feature files. Poorly written feature files can quickly turn into a nightmare of the organization. Inadequate feature files can soon become a threat to maintainability and re-usability.

Stop dumping multiple behaviors in One Scenario

The very first step to writing Gherkin is having a behavior-driven mindset. Gherkin scenarios should not be written like traditional, procedure-driven functional tests with step by step instructions with each action and the expected result associated with each step. These procedure-driven tests are often imperative and trace a path through the system that covers multiple behaviors. As a result, they may be unnecessarily long, which can delay failure investigation, increase maintenance costs, and create confusion.

For example, let’s consider a test that searches for images of ice-creams on Google. Below would be a reasonable test procedure:

  1. Step 1: Open a web browser.
    Expected: Web browser opens successfully.
  2. Step 2: Navigate to https://www.google.com/.
    Expected: The web page loads successfully and the Google image is visible.
  3. Step 3: Enter “Ice Cream” in the search bar.
    Expected: Links related to “Ice Cream” are shown on the results page.
  4. Step 4: Click on the “Images” link at the top of the results page.
    Expected: Images related to “Ice Cream” are shown on the results page.

The BAD GHERKIN transformation of the above test scenario will be:

Feature: Google Searching

Scenario: Image search in google

Given user opens the web browser
Then browser should be opened
And user navigates to “https://www.google.com”
Then google page should be visible
When user enters “Ice Cream” in google search bar
Then “Ice Cream” should be populated in the search bar
When user clicks the search button
Then “Ice Cream” links are visible in the web page
When user clicks on the image button in search result
Then “Ice Cream” pictures should be visible

This scenario is terribly wrong. All that happened was that the author put BDD buzzwords(G-W-T) in front of each step of the traditional test. This is not behavior-driven, it is still procedure-driven.

So, what went wrong?

  1. The first two steps are purely setup. They just go to Google, and they are strongly imperative. Since they don’t focus on the desired behavior, they can be reduced to one declarative step: “Given user navigates to Google home page”. This new step is friendlier to read.
  2. After the Given step, there are two When-Then pairs. This is syntactically incorrect: Given-When-Then steps must appear in order and cannot repeat (can vary in complex scenarios). A Given may not follow a When or Then, and a When may not follow a Then. The reason is simple: any single When-Then pair denotes an individual behavior. This makes it easy to see how, in the test above, there are actually two behaviors covered:
    (1) searching links from the search bar
    (2) performing an image search.
    In Gherkin, one scenario covers one behavior. Thus, there should be two scenarios instead of one.

So, a good transformation of the scenarios can be:

Feature: Google image searching

Scenario: user search links

Given user navigates to Google home page
When user enters “Ice Cream” in Google search bar
Then user is able to see links related to “Ice Cream” is shown in search results

Scenario: user search images

Given user navigates to Google home page
When user enters “Ice Cream” in Google search bar
And user clicks in image button to see “Ice Cream” pictures
Then user is able to see pictures related to “Ice Cream”

Stop making Gherkin scenarios First Person

Gherkin steps should always be written in the context of “User” (third person), not “I”. A third-person perspective is entirely generic and can expressively name any user or system component. It may be easier to write Gherkin scenarios in the first-person perspective because it helps the author to frame himself or herself in the context of the user, but it makes the steps less reusable and meaningful. Even worse, the first-person perspective can cause steps to be misunderstood. Third-person vision make the scenario more customer-focused.

What we should avoid:

Feature: Google Searching

Scenario: Image search in google

Given I am at the Google search page
When I search for “Ice Cream”
Then I see google shows images related to “Ice Cream”

What we should practice:

Feature: Google Searching

Scenario: Image search in google

Given the user opens Google search page
When the user searches for “Ice Cream”
Then the user validates google shows images related to “Ice Cream”

Stop making Gherkin scenarios Dull Phrased

Write steps as a subject-predicate action phrase. Partial phrases make steps ambiguous and more likely to be reused improperly. For example, consider the following example:

Feature: Google Searching

Scenario: Google search results page elements

Given the user navigates to Google home page
When the user entered “Ice Cream” at the search bar
Then the results page shows images related to “Ice Cream”
And new links related to “Ice Cream”
And video links related to “Ice cream”

The final two And steps lack the subject-predicate phrase format. Are the links meant to be subjected, meaning that they perform some action? Or, are they meant to be direct objects, meaning that they receive some action? Are they meant to be on the results page or not? What if someone else wrote a scenario for a different page that also had image and video links — could they reuse these steps? Writing steps without a clear subject and predicate is not only poor English but poor communication.

Also, use appropriate tense for each type of step. Givens should always use the present or present perfect tense, and Whens and Then should always use the present tense. A good example of phrasing would be:

Feature: Google Searching

Scenario: user search images in Google search

Given the user navigates to Google home page
When the user enters “Ice Cream” at the Google search bar
Then the user sees image links, video links and news links related to “Ice Cream” in search results page

Stop making Gherkin scenarios Lame Titled

Good titles should be short one-liners. One simple statement should be sufficient to concisely capture the intended behavior. Anything longer likely means that either the author doesn’t truly understand the behavior in focus, or that the scenario does not focus on one main behavior. Make sure scenario titles do not contain assertion texts like “verify that..”.


  1. The last five search phrases are saved so that the user can rerun them from the history page
  2. The user can log into the app, navigate to the profile page, and see their full name, address, phone number, email, and username
  3. Verify the user can change their address on the profile page


  1. The history page saves the last five search phrases
  2. The profile page displays the user’s personal info
  3. Profile page address change

Stop making Gherkin scenarios only Data Focused

write scenarios defensively so that changes in the underlying data do not cause test runs to fail. Furthermore, to be truly behavior-driven, think about data not as test data but as examples of behavior. Test automation should never contain hard-coded values for config data like URLs, usernames, or passwords. Rather, test automation should read config data when it launches tests and makes references to the required values. This should be done in Before hooks and not in Gherkin steps. In this way, automated tests can run on any configuration, such as different test environments before being released to production.

Use the minimal amount of test data necessary to test the functionality of the product under test. More test data requires more time to develop and manage. As a corollary, use the simplest approach that can pragmatically handle the test data. Avoid external dependencies as much as possible.

Finally, be cautioned against randomization in test data. Functional tests are meant to be deterministic — they must always pass or fail consistently, or else test results will not be reliable.

Parking Lot

The best practices described are guidance to enhance the maintainability of the Gherkin scenarios. We have to remember that each Gherkin scenario will be considered as feature documentation in the future. Well structured BDDs thus be very handy for the feature team to look back and check the functionalities tested. Scenarios should be short and sweet. I typically recommend that scenarios should have a single-digit step count (<6). Long scenarios are hard to understand, and they are often indicative of poor practices. Always remember the great words — “Less is more”.

Happy Testing!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Abhinaba Ghosh

Abhinaba Ghosh

Tech Lead Manager @Postman 🚀 | Space Movie Lover 🪐 | Coder 👨‍💻 | Traveller ⛰️