Why use “Gherkins” in Software Development?

11 min readAug 23, 2024

They may save your sanity. (Not the pickles.)

I’ve mentioned before that using Gherkins (“Gherkin syntax”) is a great idea, recommended, and should be a requirement on most projects.

But why should you use Gherkins? and why do many top companies also use them?

Most engineers want to talk mostly about code and tech stacks (me too)— but stick with me here… It will all make sense shortly. This helps both devs and non-engineers get what they want. It’s a win-win.

Gherkin syntax defined, example
Huge, Dev-Boss exchange
Why Gherkins are Valuable
Downsides?
Practical Usage: Use Gherkins and Syntax examples
Software That Uses Gherkin for Automated Tests

The other Gherkins. These taste good, but don’t help in software development typically, afaik

Defined:

Gherkin syntax is a behavior specified in a domain-specific language understandable to both engineers and non-engineers that is used for writing structured behavior specifications for software development.

First, let’s look at a simple example of what I am talking about… a basic password reset feature (we’ll also look at more later down below):

Feature: Password Reset

  Scenario: Successful password reset with valid email
    Given the user is on the password reset page
    When the user enters a valid email address
    And the user clicks the "Reset Password" button
    Then the user should receive a password reset email
    And the email should contain a reset link

Feature: “Password Reset”. It’s a feature/story (in Agile terminology) about password reset functionality.
Scenario: A feature can have multiple scenarios under a feature. This is only one. It covers the process of resetting a password with valid email. “Successful password reset with valid email”
Given: The assumptions of this scenario. Establishes that the user is on the correct page.
When: Describes the action of entering the email and initiating the reset.
Then: Specifies the expected outcome of receiving an email with a reset link.

Gherkin syntax is a domain-specific language understandable to both engineers and non-engineers that is used for writing structured behavior specifications and documenting software development.

Let’s highlight those points and dive in...

Domain-specific language (DSL): A specialized language designed for software development. This is an actual syntax and a DSL in simple Engligh language. All team members can express requirements and behaviors in a format for specific needs of software.
Understandable to both engineers and non-engineers: Gherkin is written in plain language that is accessible to all stakeholders involved in a project, including those without a technical background.

Understandability: This helps bridge communication gap — all can contribute to these and understand the project requirements. It’s not just all in code or unstructured requests.

btw, quick promo: Check out my site SystemsArchitect.io for more Cloud Engineering info, and there is also this link to the store on there too: https://store.systemsarchitect.io

Huge

This is HUGE because one of the biggest headaches of a software engineer is not getting clear requirements!

When a non-technical team member (ie. product manager/analyst) steps through the Gherkin syntax, it reveals items they FORGOT about!

That’s what previously messed up the tech team… left them grumbling… pacing around aimlessly in the empty part of Initech parking lot.

That’s one clue as to why it should be your best friend.

Structured behavior specifications: Gherkin organizes requirements into a clear, consistent format that outlines specific scenarios and expected outcomes.

A structured approach makes it easier to define and communicate the desired behavior of the software, which can be directly translated into test cases for validation. And, it can be re-used as a basis for documentation.

The point is to make planning and requirements much better. That helps YOU.

Think about all the times in your job you got bad or changing requirements.

What if every time the Gherkin changed it was a VERSION CHANGE in a Github repo?

Boss: “Why are we getting behind coding on these new features? We’ve been planning this project for months and you’ve had weeks for development and we’re still nowhere near done yet!”
Dev: “The story requests/details keep changing.
Let me pull up our repo...
As you see in the change history, the Product Analyst Maya and Project Manager Mike have made 34 changes to the request in the past month!!!
Their changes caused a lot of delays.” (shows all the version tracking and usernames)
Boss: Wow, 34 changes??? That’s freakin insane. You’re right I will talk to them, thanks for letting me know. Sorry to bother you.

Another thing — if you are an entrepreneur, and you are the one writing the Gherkins, it will help you “brainstorm” all the steps required to implement various features. And make sure you do not forget all your ideas. I do this and save ideas in startup research repos.

THEN, if you are not coding them, you can easily pass them to another dev you hired or an intern, and be more sure they get the plan.

Why Gherkins are Valuable

Collaboration: Better collaboration between business analysts, developers, and testers by providing a common language to discuss requirements and expected behavior.
Use in Test Executable Automation: Gherkin scenarios can be directly linked to automated tests using tools like Cucumber, turning specifications into executable test cases.
Clarity and Precision: Gherkin helps articulate business requirements in a clear and precise manner, ensuring that all stakeholders have a mutual understanding of what needs to be built. That’s what we need for good software.
Documentation: It‘s living documentation, allowing teams to track changes and updates to requirements in a format that is always up-to-date with the latest project developments. You could even check these into Github and use with versioning. Ever have an issue with disagreements over changing requirements?
Reduction of Misunderstandings: By specifying acceptance criteria in a standardized format, Gherkin helps reduce the risk of misunderstandings and ensures that all requirements are met.
Supports Agile Practices: Gherkin aligns well with Agile methodologies by enabling iterative development and frequent adjustments based on feedback and evolving requirements.
Integrate into other Software Tools: You can use automated tools and AI to convert Gherkin requests to schemas, code, and other technical syntax and format. (shhh… you can put it in the AI, outline components, and get code output… keep this one quiet, big timesaver!!!)

Over time, Gherkin has evolved to become a standardized language for writing BDD scenarios. Behavior Driven Development. You could even say it has some relation to DDD — documentation driven development.

Its syntax and structure have been refined to support various testing needs and integrate with different tools and frameworks. It has become widely adopted in the BDD community and beyond.

🥰 If you like this topic/article, please give some claps (it’s free), bookmark, add to your list and share with colleagues. 🥰

Downsides?

What are the downsides?

Honestly not much really. Even though these downsides could arise, the benefits noted above are far more frequent.

Complexity: Some feel that it introduces extra complexity. Some features may not be as easy as others to translate to the gherkin syntax.
Ambiguity: If people are being half-assed about it, then the scenarios and descriptions could be really vague and not help the development process.
Time-consuming? If this basic syntax is too difficult or a product manager is too lazy to do it in a few minutes per scenario… while asking devs to spend countless hours coding it and fixing it… Let’s just say dev time is valuable. It can be re-used in the user story (scrum). There’s no time excuse.

Practical Usage: Use Gherkins for Planning

Use the below info to get started with your team.

Gherkin syntax is now maintained as an open standard and is used across various tools and frameworks.

Many teams make their own variations but I suggest staying as close as possible to the formal specification. You may need to if you use in automated tools, even later.

📚 Define Scenarios: Start by outlining specific scenarios in plain language that describe expected behavior.

Feature: Declares the feature being tested.

Example: Feature: User login

Scenario: Defines a specific test case or situation within the feature.

Example: Scenario: Successful login with valid credentials

Given: Sets up the initial context or state before an action is performed.

Example: Given the user is on the login page

When: Describes the actions or events that trigger a change.

Example: When the user enters valid credentials

Then: Specifies the expected outcomes or results after the action.

Example: Then the user should be redirected to the dashboard

And: Adds additional steps to a Given, When, or Then clause.

Example: And the user should see a welcome message

But: Adds a negation to a Given, When, or Then clause.

Example: But the user should not see an error message

Background: Defines steps that are common to all scenarios in a feature.

Example: Background: Given the user is logged in

Examples: Provides example values for Scenario Outline to run multiple scenarios.

Example: Examples: | username | password |

Scenario Outline: Defines a scenario template that runs with different sets of examples.

Example: Scenario Outline: Login attempt with multiple users

Doc Strings: Allows for multi-line text in steps.

Example: Given the following text: <multi-line text>

Data Tables: Allows for tabular data in steps.

Example: Given the following users: | username | password | | user1 | pass1 |

Tags: Adds metadata to features or scenarios to control execution.

Example: @smoke @login

Rule: Defines a set of scenarios related to a specific business rule (less common).

Example: Rule: User login with valid and invalid credentials

see more: Gherkin Syntax

More examples:

Feature: User Login

  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    And the user clicks the login button
    Then the user should be redirected to the dashboard
    And the user should see a welcome message

Feature: Shopping Cart

  Scenario: Add an item to the shopping cart
    Given the user is on a product page
    When the user selects a product and clicks "Add to Cart"
    Then the item should be added to the shopping cart
    And the shopping cart count should increase by 1

🤝 Collaborate with Stakeholders: Engage with stakeholders to review and refine scenarios. Ensure that the scenarios accurately reflect the business requirements and acceptance criteria.

🔄 Use Tools for Automation: Integrate Gherkins with tools like Cucumber to automate tests based on your scenarios. This ensures that the specifications are directly linked to test cases.

🗂️ Maintain and Update: Regularly review and update Gherkins scenarios to reflect changes in project requirements or scope. This keeps documentation relevant and accurate.

🔍 Review and Refine: Continuously review scenarios to identify any gaps or ambiguities. Use feedback from testing and development teams to enhance the clarity and completeness of scenarios.

15 Quick Tips To Improve Your BDD Gherkin Writing

Make your Gherkin writing clearer with these tips.

drpicox.medium.com

Software That Uses Gherkin for Automated Tests

You do not have to use Ghekins with the software below. tbh, I don’t regularly, and have only dabbled with a couple of these.

You can get a lot of value out of Gherkin syntax without integrating into tools. At NIKE, my team just used them for developing scrum stories and pointing, not embedded in testing software itself.

However, if you are ambitious you might accrue a lot of additional value by integrating into tools like these:

Cucumber
One of the most popular tools for BDD, and an original, Cucumber uses Gherkin to define test scenarios. It executes the scenarios described in Gherkin syntax and validates the behavior of the application against the defined expectations.

https://cucumber.io/

Many well-known DevOps tools can leverage Gherkin for automated tests using extensions, add-ons or built in functionality:

Jenkins: integrate with Cucumber through plugins like the Cucumber Reports Plugin, which allows Jenkins to execute Cucumber tests and generate detailed reports.
GitLab CI/CD: Cucumber tests as part of its pipelines using custom scripts or Cucumber integration plugins.
Travis CI: execute Cucumber scenarios and integrate the results into the build process.
CircleCI: can be set up to execute Gherkin scenarios and provide feedback on test results.
Azure DevOps: integrate with Cucumber through extensions and scripts to run automated BDD tests and track results.

Other tools
I have not use these specific ones yet, but have been recommended

SpecFlow
A BDD framework for .NET that leverages Gherkin to write test scenarios. SpecFlow integrates with various .NET testing frameworks and supports the execution of Gherkin scenarios.

Behat
A BDD framework for PHP that uses Gherkin to write behavior specifications. Behat helps in testing the behavior of PHP applications in line with the defined scenarios.

Katalon Studio
A testing tool that supports Gherkin syntax for writing BDD test cases. Katalon Studio integrates with various testing frameworks and provides a comprehensive environment for test automation.

I have a couple new Ebooks you may want to check out:

Ebook: Buy my Cloud Audit ebook / store: SystemsArchitect Store

About me

I’m a cloud architect, senior developer and tech lead who enjoys solving high-value challenges with innovative solutions.

I’m always open to discussing projects. If you need help, have an opportunity or simply want to chat, you can reach me on X/Twitter @csjcode and same username gmail. Also, can schedule a Zoom here (lower on page): https://systemsarchitect.io/docs/consulting

I’ve worked 20+ years in software development, both in an enterprise setting such as NIKE and the original MP3.com, as well as startups like FreshPatents, SystemsArchitect.io, API.cc, and Instantiate.io.

My experience ranges from cloud ecommerce, API design/implementation, serverless, AI integration for development, content management, frontend UI/UX architecture and login/authentication. I give tech talks, tutorials and share documentation of architecting software. Also previously held AWS Solutions Architect certification.

Cloud Ebook Store — check for 50% off sales cloud architect and engineering books, “Cloud Metrics” (800 pages+) and “Cloud Audit” (800 pages+) and more — https://store.systemsarchitect.io

And my website:

Recently I’m working on Instantiate.io, a value creation experiment tool to help startup planning with AI. I write a reference manual on cloud metrics.

Also, an enthusiast of blockchain, I’m active working on applications in the innovative Solana blockchain ecosystem.

Thanks for reading ! 🥰 If you like this topic, please give some claps (it’s free), bookmark, add to your list and share with colleagues. I follow back. I’m here to meet people, learn, and contribute. 🥰