top of page

Writing better Gherkin

Feature files are the core of cucumber data driven testing, as they define the scenarios, steps, and examples that guide the automation and validation of your application's behavior. But how do you write effective feature files that are clear, concise, and consistent? In this article, I will show some best practices and tips for creating feature files that follow the principles of behavior-driven development (BDD).

There are several ways to make your Gherkin better. Before you write any feature file, you need to understand the business value and goal of the feature you are testing. What problem does it solve for the user? By answering this question, you can write a feature description that summarizes the purpose and scope of the feature. Write feature files so that everyone can easily understand them. Good Gherkin should improve team collaboration by clarifying behaviors you want to develop. When Gherkin is tough to read, teams can't develop good behaviors.

Consider the following scenario:

This scenario is declarative because it doesn't provide enough information about the desired behavior. What shirts? How are they purchased? How will you verify the purchase?

Now, consider the opposite:

This scenario is imperative because it provides too much detail. You can automate each step, but collaboration will be tough.

Here's how to write these:

In the above image, the steps strictly follow a given-when-then order that clearly shows the interaction and the verification of the desired behavior. It is a much better scenario than the others.

Another rule to write good gherkin is one-to-one rule: One scenario should cover exactly one single, independent behavior.

Consider this scenario:

In the above scenario, it covers two separate behaviors: searching for shirts, and searching for images of shirts. Whenever a scenario has more than one when-then pair, it covers more than one behavior. Better way to write is:

We can take the stopping point for the first scenario as a new given step for the second scenario. In this way, the second scenario focuses only on its unique behavior.

One more rule is testing the most important things and avoid testing duplicate things.

Consider the following scenario:

Scenario outlines run the scenario, one for each row in the examples table, so this scenario outline would run four times. All these examples just cover different types of shirts. Testing different types of shirts may not be worthwhile. Always carefully consider the examples chosen.

One last rule to write good gherkin is, Language matters. Behavior scenarios are meant to readable and expressive. Steps are meant to be reusable. Scenarios can become confusing, and team members could use steps out of context.

One of the biggest problems with gherkin is an inconsistency point of view. You can write steps using first person perspective("I,me,my") or third person perspective (" the user"). It's better to write in third person for gherkin steps.

Take a look at this scenario in first person:

In the above scenario, it is understandable, but the meaning could be ambiguous: Am "I" "the user," or is there a second user?

A problem many frequently see involves tense: past, present, and future. Each step should follow same rules. Here are some rules:

  • Given steps should use past or present-perfect tense, because they represent an initial state that must already be established.

  • When steps should use present tense, because they represent actions actively performed as part of the behavior.

  • Then steps should use present or future tense, because they represent what should happen after the behavior actions.

I hope the rules I wrote in this blog helps you with the writing of good gherkins.

106 views0 comments

Recent Posts

See All


Rated 0 out of 5 stars.
No ratings yet

Add a rating
bottom of page