How To Start Writing Gherkin Test Scenarios?

How To Start Writing Gherkin Test Scenarios?

・8 min read
How To Start Writing Gherkin Test Scenarios?

You may also like:

How To Navigate Digital Transformation In eLearning?

How To Navigate Digital Transformation In eLearning?

Read more

Gherkin Syntax is a buzzing word nowadays in the software development world. But many developers and businesses are yet unfamiliar with Gherkin technology.

Some time ago, I published a Beginner’s Guide to Gherkin. Now it is time to tackle the topic in more detail. In this post, we will finally learn how to write Gherkin test scenarios successfully. Are you ready? Let’s begin.

Step 1: Get Familiar with the Basics of Gherkin Syntax

Gherkin is a machine-readable business language that allows you to define business activity without getting entangled in technical specifics. It's a domain-specific language for defining requirements tests in Cucumber format. It describes use cases in simple Terms and helps users to eliminate logic elements from behavior testing.

What is Gherkin Syntax?

Gherkin, like YAML and Python, is a line-oriented programming language. Each line in the terminals is referred to as a step, and it begins with keywords and ends with a stop. Indentation is done with a tab or space.

A comment can be placed anywhere in this script, but it must begin with the # symbol. After deleting Ghrekin's keywords like given, when, and so on, it reads each sentence.

The following are examples of typical Gherkin steps:

Gherkin Scripts: bridges the gap between the human idea of cause and effect and the software model of input/process/output.

Gherkin Syntax:

Feature: Title of the Scenario
Given [Preconditions or Initial Context]
When [Event or Trigger]
Then [Expected output]

Step 2: Know the Gherkin keywords


Each line that isn't blank must begin with a Gherkin keyword and then be continued by any content you choose. The functionality and scenario explanations are the only exceptions. I described those keywords in more detail in the post Beginner’s Guide To Gherkin.

Primary Keywords

Secondary Keywords

  • " (Doc Strings)
  • | (Data Tables)
  • @ (Tags)
  • Comments

Left map imageRight map image
Avoid costly mistakes with our QA engineers
Contact Us

Step 3: The Simple Rules for Gherkin Developers

There are some golden rules to always keep in mind for Gherkin and these are as follow:

The Golden Rule of Gherkin

The Golden Rule of Gherkin is straightforward: treat other readers the way you want to be treated. Create functionality files in a way everybody can comprehend them easily. By defining the behaviors you wish to cultivate, a successful Gherkin should increase team cooperation. If Gherkin scenarios are tough to read, teams can’t develop good behaviors

Write scenarios in an intuitive manner and test scenarios shouldn’t be ultra-declarative or ultra-imperative.

Ultra-Declarative Example:


What seems to go wrong here:

  • It is too vague
  • Steps are not procedural - not automatable
  • Lacks accountability - it omits conditions for success

Let’s check Ultra-Imperative example:



  • It is too much in detail
  • Steps name manual, low-level interactions
  • Wall of text worsens the understandability and collaboration

Here’s the correct Example:


  • The scenario has declarative, descriptive steps
  • Given-When-Then order is followed
  • Interaction and desired behavior are clearly shown
  • Concrete example helps the reader to understand the scenario

The Cardinal Rule of BDD

The cardinal rule of BDD is a one-to-one rule: each scenario should cover precisely one single, independent behavior. Concentrating on one behavior at a time provides several advantages:

  • Collaboration: More clarity and less ambiguity
  • Automation: Each test failure identifies a separate issue.
  • Efficiency: Less complicated Work has a shorter cycle time.
  • Traceability: consists of one behavior, one example, one situation, one test, and one outcome.
  • Accountability: Teams are not allowed to hide or avoid behaviors.

Example of an Incorrect Scenario:


What’s wrong here?

  • Covers two separate behaviors (two When-Then pairs)
  • If you included two or more Given-When pairs in your test, it’s better to split them to a different Gherkin scenario (below)

There are times when it is more convenient and acceptable to write multiple ‘When-Then’ pairs but it should be avoided in general.

The Unique Example Rule

When it comes to instances, sometimes less is more, therefore leave out the ones that aren't required. Instead, concentrate on unique equivalence classes. While testing "everything" may seem appealing, it is a waste of time. Instead, focus on the most critical aspects of your project and minimize testing duplicates.



What’s Wrong Here!

  • In the example above, the scenario would run 6 times - 1 for each row in the examples table
  • Though testing “all the things” may be tempting, it’s better to test the most important things, and avoid testing duplicates

The Golden Rule of Grammar

Because language is important, write as though your high school English instructor is grading your Gherkin. The goal of behavior scenarios is for them to be legible and expressive. Steps are designed to be reused. The benefits of behavior specification can be ruined by poor syntax, misspellings, and contradictory phrasing. Scenarios might get perplexing, and team members may employ actions that aren't relevant to the situation.

Example # 1:


What’s Wrong Here!

  • The above scenario is inconsistent and ambiguous - it’s not clear whether “I” am “the user” or if there is a third party involved. Moreover, using the third-person perspective exclusively is more elegant.
  • Phrase steps as you would write regular sentences

Example # 2:


What’s Wrong Here!

  • Phrase steps as you would write regular sentences
  • We don’t know if the above steps verify the existence of the links or click them - we need to clarify them:

Correct Example:


Step 4: Write Good Titles

For well-written scenarios, creating strong titles is simple. An excellent Gherkin scenario concentrates on a single specific action. Take a pause and ask yourself, "Is this scenario a good scenario?" To help you build amazing scenarios, see the post 4 Rules for Writing Good Gherkin or Paul Merrill's blog.

  • A title should be a short one-liner.
  • When using conjunction words like "and", "or" and "but" be cautious since they imply that more than one action may be done.
  • Avoid using conjunctions like "because", "since" and "so" since they explain why the scenario exists, while we should be concentrating on what the action is - why may be derived from the stages or described with comments.
  • Avoid assertion language - don't use terms like "verify" "assert" or "should" since they focus on the statement rather than the action.
Left map imageRight map image
Leverage QA standards to grow your business.
Learn More

Step 5: To Make Your Life Easier, Install Plugins or Packages


Cucumber is easier to work with when you have the appropriate tools.


Gherkin syntax highlighting is supported by the majority of popular text editors.

Advanced Cucumber support is available in certain IDEs, including the ability to run Cucumber from inside the IDE, view results, navigate between Gherkin phases, and so on.


It is a text editor for Windows, macOS, and Linux that offers several different packages to use with Gherkin.


It is a dedicated text editor for macOS to use with Gherkin. It helps boost the documentation process while developing scenarios.

Visual Studio Code

It is not a text editor but a code editor specifically designed for Windows, macOS, and Linux. It can be used with a plugin with Gherkin Syntax.


IDEs is another plugin that can be used for different languages keeping as a plugin for Gherkin. There are different IDEs such as:

Build Tools

You can run Gherkin using build tools rather than from the command line.


Gherkin is the cucumber specification format. Like YAML and Python, it is a line-oriented language that combines the human idea of cause and effect with the technical concept of input/process and output. It makes extensive use of the terms feature, background, scenario, given, when, then, and but.

Gherkin is easy enough for non-programmers to comprehend. If you are looking for a team expert in Gherkin Syntax, don't hesitate to contact Selleo. We have Gherkin specialized developers to answer all your concerns. Contact us Now!

Rate this article:


based on 0 votes
Our services
See what we can create for You
Our services

Awards & Certificates

reviewed on
30 reviews
  • Top 1000 Companies Global 2021
  • Top Development Company Poland 2021
HR dream team
  • 2020 HR Dream Team Award
  • 2016 Employer Branding Featured
  • 2015 HR Dream Team Award
ISO CertificateISO CertificateAWS Certificate
  • Information Security Management System compliant with PN-EN ISO/IEC 27001
  • Business Continuity Management compliant with ISO 22301
  • AWS Certified Solutions Architect - Associate