Selleo Labs spółka z o.o.

I am an ISTQB-certified Software QA Tester with over three years of experience. My job is to support the development teams at all stages of product development, from project kick-off to testing. I enjoy taking on new challenges and finding the best project solutions with Product Owners. 

Tomasz Szyrner

\[TOC\]

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](https://selleo.com/blog/beginners-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

![Img](https://a.storyblok.com/f/86602/720x246/eb3308d72a/step-2.jpeg)

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](https://selleo.com/blog/beginners-guide-to-gherkin).

### Primary Keywords

- [Feature](https://cucumber.io/docs/gherkin/reference/#feature)
- [Rule](https://cucumber.io/docs/gherkin/reference/#rule) (as of Gherkin 6)
- [Example](https://cucumber.io/docs/gherkin/reference/#example)
- [Given](https://cucumber.io/docs/gherkin/reference/#given), [When](https://cucumber.io/docs/gherkin/reference/#when), [Then](https://cucumber.io/docs/gherkin/reference/#then), [And](https://cucumber.io/docs/gherkin/reference/#and-but), [But](https://cucumber.io/docs/gherkin/reference/#and-but) for steps (or [\*](https://cucumber.io/docs/gherkin/reference/#Asterisk))
- [Background](https://cucumber.io/docs/gherkin/reference/#background)
- [Scenario Outline](https://cucumber.io/docs/gherkin/reference/#scenario-outline) (or [Scenario Template](https://cucumber.io/docs/gherkin/reference/#scenario-outline))
- [Examples](https://cucumber.io/docs/gherkin/reference/#examples) (or [Scenarios](https://cucumber.io/docs/gherkin/reference/#examples))

### Secondary Keywords

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

<Baner name={qa} />

## 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:**

![Img](https://a.storyblok.com/f/86602/204x88/909e32d5e9/image6.png)

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:

![Img](https://a.storyblok.com/f/86602/445x331/8500fb1c1b/image4.png)

Now,

- 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:**

![Img](https://a.storyblok.com/f/86602/387x105/e5bc9cf4fb/image10.png)

- 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

<ReadMore> Read also: [How To Streamline And Improve Your Process? 6 Steps To Follow](https://selleo.com/blog/how-to-streamline-and-improve-your-process-6-steps-to-follow) </ReadMore>

### 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:**

![Img](https://a.storyblok.com/f/86602/429x115/457712a3e2/image13.png)

***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.

**Example:**

![Img](https://a.storyblok.com/f/86602/368x229/528c0c91d7/image.png)

***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:**

![Img](https://a.storyblok.com/f/86602/301x77/69f26cb040/image11.png)

***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:**

![Img](https://a.storyblok.com/f/86602/250x61/489db77b18/image3.png)

***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:**

![Img](https://a.storyblok.com/f/86602/396x48/8f5fd6a9c3/image1.png)

## 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](https://automationpanda.com/2020/02/21/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.

<Baner name={qa-landing} />

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

![Img](https://a.storyblok.com/f/86602/720x245/c9a26d3146/step-5.jpeg)

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

### Editors

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.

### Atom

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

### TextMate

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.

<ReadMore> Read also: [Why Do We Need QA Engineers?](https://selleo.com/blog/why-do-we-need-quality-assurance-engineers) </ReadMore>

### IDEs

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

- [Java IDEs](https://cucumber.io/docs/tools/java#ides)
- [Ruby IDEs](https://cucumber.io/docs/tools/ruby#ides)
- [CukeTest](http://cuketest.com/) tool

### Build Tools

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

- [Java build tools](https://cucumber.io/docs/tools/java#build-tools)
- [Ruby build tools](https://cucumber.io/docs/tools/ruby#build-tools)

## Conclusion

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!](https://selleo.com/contact)

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?

How To Start Writing Gherkin Test Scenarios?

\[TOC\] 
Good communication can not only improve the understanding of team members and positively influence their collaboration skills but also speed up the process of software development. Practices like Behaviour-Driven development influence the communication between the so-called ‘three amigos’ - business, development and testing.

All that can be achieved by using the Gherkin language - one of the most popular languages for writing behaviour specifications. This article will serve you as a beginner guide to Gherkin. You will find out how to use it in practice and how it will help you improve your organisation.

## What is BDD?

Before diving into Gherkin, we need to focus on the basic rules of testing for a bit. One of those rules is Behaviour-Driven Development. BDD grew out of Test-Driven Development (TDD) and Acceptance Test-Driven Development (ATDD) and is a part of Agile software development processes that encourages collaboration among developers, QA and non-technical business participants in a software project.

BDD focuses on identifying the desired behaviour of a given feature from the very beginning. The behaviour here means how a product or feature operates and is defined as a scenario of inputs, actions and outcomes.

![Img](https://a.storyblok.com/f/86602/720x326/d8a5a88116/benefits-of-bdd.jpeg)

A product or feature has countless behaviours and identifying them brings clarity and simplicity. Those behaviour specs are written with realistic examples and serve as both the product’s requirements/acceptance criteria and its test cases after development. BDD aims to improve communication between team members, support clarity and minimise hand-overs. The key points of Behaviour-Driven Development are:

* BDD is a paradigm shift
* BDD focuses on behaviour first
* BDD is specification by example
* BDD is a refinement of the Agile process

BDD also encourages applying the [‘Five Why’s’](https://en.wikipedia.org/wiki/Five_whys) principle to each user story to find a clear purpose for them.

<Baner name={qa} />

## What is the Gherkin language?

![Img](https://a.storyblok.com/f/86602/720x355/43e835a71b/what-is-the-gherkin-language.jpeg)

[Gherkin](https://cucumber.io/docs/gherkin/) is one of the most popular domain-specific languages for writing use cases for a software system in plain language. It promotes behaviour-driven development and allows developers, managers and business officials involved in the process to clearly understand the requirements of the project and the life-cycle. What is more, Gherkin’s text acts as documentation and skeleton of automated tests.

The official Gherkin language standard is maintained by [Cucumber](https://cucumber.io/) - an open-source software testing tool that supports BDD. Cucumber works with Gherkin syntax structures because they are plain text making them easy to read. Cucumber reads Gherkin tests and validates the code checking if it performs as it should. Then, it creates a report showing if each step and scenario was successful.

<ReadMore> Read also: [How To Streamline And Improve Your Process? 6 Steps To Follow](https://selleo.com/blog/how-to-streamline-and-improve-your-process-6-steps-to-follow) </ReadMore>

## How are Gherkin test scenarios useful?

Now you might be wondering why it is worth directing your attention towards Gherkin. How will it improve your communication and in return, the development process? Let’s discuss.

### Benefits of BDD

You should consider choosing Behaviour-Driven Development for several reasons and benefits like:

* **clarity** - scenarios focus on expected behaviours, which are described in plain language. Clarity ensures customers get what they want.
* **automation** - BDD makes turning scenarios into automated tests easy
* **inclusion** - it is all about collaboration, which means everybody from the customer to the tester is engaged in the product development process
* **speed** - BDD was designed to speed up the development since scenarios are requirements, acceptance criteria, test cases and test scripts all in one.
* **momentum** - BDD has a snowball effect - scenarios are easier and faster to write and automate as more definitions are added. They also often share common steps.
* **shift left** - ‘shift left testing’ means testing earlier in the development process, which results in fewer bugs later.
* **artefacts** - scenarios can form a collection of self-documenting test cases, which can be turned into a regression test suite.
* **reusable code** - some of the steps can be reused between scenarios. Automation coded becomes very modular.
* **test-driven** - BDD is an evolution of TDD. Creating scenarios from the beginning introduces quality-first and test-first mindset.
* **variation** - with scenario outlines it is easy to run the same scenario with different combinations of inputs, which is an amazing way to expand test coverage without code duplication
* **parameterization** - scenarios steps can be parametrized to be even more reusable. It is helpful for the team to adopt a common, reusable set of steps, which inspires healthier discussions when writing scenarios.
* **adaptability** - BDD scenarios are easy to update as the product changes

<Baner name={qa-landing} />

### Advantages of Gherkin

You might know the benefits of Behaviour-Driven development, but what about Gherkin? What are the advantages of using it? There are quite a few of them:

* simple even for non-programmers
* a solid base for tests
* it is easy to reuse code in other tests
* User Stories are simple to comprehend
* Gherkin Tests cases link acceptance tests directly to automated tests
* scripts can be easily understood by both business executives and developers
* Gherkin Testing targets business requirements

<ReadMore> Read also: [How To Conduct End-To-End Testing In Endtest.io?](https://selleo.com/blog/how-to-conduct-end-to-end-testing-in-endtest-io) </ReadMore>

In my opinion, the most important advantage of Gherkin is **understandability:**

1. **It is simple for everyone to understand (QA’s, developers and people not associated with programming or software in general)**
2. **Gherkin script can easily be understood by business executives and developers (basically the same as above)**
3. **Little to no previous experience is required in order to understand a small Gherkin command set**

What is more, using Gherkin means better communication, which leads to faster time-to-market and its test scenarios can be useful in many ways:

1. As a simple documentation
2. They help to track test automation coverage
3. They can be used for test automation

Fun fact: Gherkin language uses only 10 keywords, which makes it super easy.

## Gherkin test basics

Now let’s talk about Gherkin in practice. However, before you start writing, you should understand some Gherkin-related keywords:

### Feature

Gherkin documents start with this keyword, preceded by text that provides a description. Simply put, a feature is a description of what the software should be doing. It is also used to group scenarios together. The file should have a \`.feature\` extension and each feature file should have only one feature.

Note: Free-form description can also be written below the keywords as long as none of the lines starts with a keyword.

### Rule

The ‘rule’ keyword represents one business rule that has to be included as it provides context for a feature. Keep in mind that those rules should have more than one scenario.

### Given

‘Given’ steps set the scene for the scenario. Most often they describe something that took place in the past. This gives the system context before users start interacting with it.

### When

‘When’ means action steps. It describes an event like one triggered by another system or a user interacting with it. Note that it is recommended to have only one ‘when’ step for each scenario.

### Then

‘Then’ is the outcome step. This is where you describe what the system is supposed to do. This should be something that can actually be seen as a result like a report or a message.

### And, But

They can be used when you have several of one of the step types. They help to keep the documentation readable and organized. ‘But’ keyword can easily be replaced by a properly used ‘And’, which helps to keep the number of keywords as low as possible and provides consistency throughout the test scenario.

### Background

The background allows adding more context to the scenarios in a ‘feature’. This is where you can provide more than one ‘given’ step.

### Scenario Outline

This includes an examples section and can be read as a template. The scenario outline runs once for each of the example sections.

## Summary

Behaviour-Driven Development is an amazing way to help your team communicate and collaborate better. As it focuses on the actual features’ behaviour it is great for testing APIs and web UIs. It helps to clarify requirements, discover new use-cases and make timely decisions. It also supports developers and encourages confidence.

Gherkin is one of the most popular languages for writing behaviour specifications as it captures the ‘Given-When-Then’ scenarios. What is more, it makes it easy to turn those scenarios into automated test cases and is easy to understand.

In the next post about Gherkin, we will go through the testing process and present how to write good tests, so keep your eyes peeled!

If you are looking for a team of developers that know how to work with BDD or Gherkin and can take care of your project from start to finish, you are in the right place. Feel free to [contact Selleo](https://selleo.com/software-quality-assurance-services) to discuss your idea further, get to know the team and start the development now!

This article will serve you as a beginner guide to Gherkin. You will find out how to use it in practice and how it will help you improve your organisation.

CTOs

Founders

Read Our Blog.
Make better products with us.

Knowledge hub

Business

Technology

Explore our latest articles

How To Start Writing Gherkin Test Scenarios?

Beginner's Guide To Gherkin

SaaS Founder Starter Academy

CTOs

Founders

Read Our Blog. Make better products with us.

Knowledge hub

Business

Technology

Explore our latest articles

How To Start Writing Gherkin Test Scenarios?

Beginner's Guide To Gherkin

SaaS Founder Starter Academy

Read Our Blog.
Make better products with us.