Cover image for Specifying good requirements in Gherkin - BDD

Specifying good requirements in Gherkin - BDD

allanjeremy profile image Allan N Jeremy ・1 min read

First of all. Happy new Year!


Explain how to write good Gherkin, beyond just the syntax Like I'm five.

So. I just started learning Behavior Driven Development (BDD) seriously. I stumbled upon Gherkin while looking into Cucumber.

For those who may not know, Gherkin is a language that makes it easy for businesses to write down requirements for a system that fulfills business needs. This reduces the chances of wasting time in development where there is a disconnect between the tech team and the product owner or business team.

However, while trying to actually implement the actual Gherkin. I have found it difficult to establish the following things:

  • What counts as a Feature?
  • What counts as a Scenario? When should you pull out a scenario and make it a feature and when should you make a feature a scenario?
  • What makes good Given statements?
  • Why not split individual And sections into their own scenarios in most cases?

I speak from naivety and would like to understand what makes for good Gherkin and good requirements specification

Posted on by:

allanjeremy profile

Allan N Jeremy


King Maker • Future billionaire • Inventor • Software engineer • Flutter • Node • Unreal engine • Vue & a bunch of tech I'd be more of a nerd admitting


Editor guide

Here's how I see it.

A scenario specifies a single user interaction with the system, or a single event that causes a user observable system reaction.

A trivial example for a scenario could be "put product in shopping cart".

Don't specify user interface details in the scenarios, because when the user interface changes, you would have to adapt your scenarios. So instead of writing "given that the user entered John in the First Name textbox and Smith in the Last Name textbox"
write something like "given that the user's name is John Smith".

Given describes the state the system is in before the interaction/event occurs. In other words, the preconditions. It does NOT describe the sequence of user interactions to get into that state, otherwise you would couple yourself too much to the workflow.

When describes a single user interaction or event that causes some system reaction.

Then is the outcome, that is the state that the system is in afterwards.

Features are just groups of logically related scenarios. For example all scenarios that affect adding / removing products from the shopping cart.

I found the Cucumber Gherking reference to have some more hints to.


Spot on! Comments like these are the reason I love dev.to

Thanks a tonne Bertil. That does clarify a lot.

Don't specify user interface details in the scenarios, because when the user interface changes, you would have to adapt your scenarios

I get the feeling this will be golden advice in the near future. This brings the question;do you use Gherkin to model the frontend or backend or the entire system? In this case, I mean with the scenario breakdowns. Would that be e2e or just backend or frontend? What are your thoughts on how they should be structured from a dev breakdown perspective? 😅 that was a lot of '?'s


Neither frontend, nor backend. Whole system from an external user's perspective.

Got it. Thanks a tonne!