Article thumbnail

The Gherkin Convention in a nutshell



Unleash Gherkin's BDD power. Craft clear, non-implementation-specific scenarios using this human-readable format, often paired with testing frameworks.

Understanding Gherkin convention

The lesson is based on the following documentation: Gherkin convention in Cucumber framework.

If you've been involved in a real project, you've likely encountered a scenario where someone articulated feature requirements in a somewhat chaotic manner. To compound matters, individuals tend to express these requirements using varying syntax and formats. It's not uncommon to come across situations resembling the following:


Typically, for smaller projects, simplicity may suffice; however, our minds tend to appreciate consistency. Engaging in a repetitive, uniform approach not only facilitates ease of recollection but also enhances readability.

That's precisely why a clever individual introduced the Gherkin convention, placing a strong emphasis on consistency, repetition, and readability.

Gherkin is like a simple way of writing down what you want a piece of software to do, but without getting into the nitty-gritty of how it's actually done. People often use it in a teamwork approach called behavior-driven development (BDD) and pair it up with testing tools.

Picture a tool that comprehends plain text instructions, capable of executing those steps as described. It's mind-boggling how it combines the insane ability to understand and execute tasks while remaining as clear as "holy moly" in its readability!

Let's articulate the scenario for the sign-in feature using Gherkin to better illustrate the contrast.


So, the primary purpose of Gherkin is to add:

  • Clarity and readability
  • Collaboration
  • Requirements traceability
  • Automated test generation
  • Living documentation
  • Reusability and modularity
  • Cross-Team consistency
  • Behavior-Driven Development (BDD)
  • Reusability
  • Easy migration to other language that supports e2e testing

In summary, Gherkin provides a bridge between business requirements and automated tests, promoting collaboration, clarity, and efficiency throughout the software development lifecycle.

Gherkin keywords

Gherkin scenarios are written using a set of predefined keywords such as:

  • "Feature" - describes a high-level feature or user story
  • "Scenario" - represents a specific test scenario
  • "Given" - describes the preconditions
  • "When" - describes the actions
  • "Then" - describes outcomes of actions
  • "And" - additional precondition/action/outcome
  • "But" - used to contrast the expected outcome with an unexpected or negative outcome. It's typically used to add clarity to the scenario


Using Cucumber in Cypress

Ensure that you have a functional Cypress setup in place before proceeding! If not, here you've a: Cypress setup guide.

If you wish to bring your scenarios to life, you require an interpreter like Cucumber. This enables you to associate dedicated test commands with specific outcomes in the executed code behind the scenes. So, type npm i cucumber cypress-cucumber-preprocessor --save-dev and enjoy the power of single source of truth in your tests!




Comparing plain Cypress tests with Gherkin/Cucumber

If your tests are composed in the following manner, you're likely to encounter difficulties and potentially impede your progress.


Install the required packages as mentioned earlier, include scenarios in Gherkin, and implement logic for dedicated commands. This approach enables you to reuse them in subsequent tests, leading to a substantial enhancement in both writing speed and readability.



The elegance of Gherkin

Imagine now, if your team is not proficient in JavaScript (like me), and you aim to implement your test logic using Java. In this scenario, you only need to modify the logic of the commands instead of migrating the entire test suite. The test scenarios remain unaffected, with only the inner workings undergoing changes.


As evident, transitioning to another testing technology demands significantly less effort with the incorporation of Gherkin!

The often overlooked advantages of Gherkin

One of the major but often overlooked advantages is the potential for non-developers to write tests automatically. Envision a scenario where analysts or project owners adhere to the prescribed syntax, and testers or developers merely need to correct any typos from a Jira ticket to seamlessly transform the test into an automated one!

Moreover, Gherkin can be applied in your unit and integration test layers, presenting an incredible opportunity to enhance the readability of every test.

Full example presentation

Conclusions and reflections

Gherkin is a genuine game-changer, offering numerous benefits with intelligent effort and swiftly automating your tests. The key is to encapsulate commands with logic behind the scenes, whether it's in JavaScript, Java, or your preferred language.

The tool introduces crucial consistency, a pivotal element for well-defined e2e tests. By fully leveraging BDD, it brings abstraction tailored for humans rather than computers.

I create content regularly!

I hope you found my post interesting. If so, maybe you'll take a peek at my LinkedIn, where I publish posts daily.


Add your honest opinion about this article and help us improve the content.

created: 10-04-2023
updated: 10-05-2023