How to write scenarios using Gherkin language

Editor’s note: This article was reviewed and updated on 15 October 2024 to improve clarity and provide additional context about Gherkin and its benefits for product management.

Writing “good enough” acceptance criteria used to drive me nuts. Some developers would complain it was too abstract, and others would say it was too prescriptive. I struggled to find balance.

One day, an experienced software engineer invited me for a coffee. I was curious about what he had to say, and he shared a way to provide enough guidance to the team. That’s how I learned about Gherkin. That transformed our collaboration for the better. I’m thankful for those magic ten minutes that we chatted.

Let me help you understand what Gherkin is about, how and when to use it, advantages and disadvantages.

What is Gherkin?

Gherkin is a plain-text language with a simple structure. It allows you to concisely describe test scenarios and examples to illustrate business rules in real-world domains.

The goal is to give clear context for business scenarios and accelerate test automation. Gherkin uses simple keywords that can be quickly translated into automated tests and understood by non-programmers — “scenario,” “given,” “when,” “then,” and “but.”

You can use Gherkin syntax in UX and product management to write clear, simple acceptance criteria and user stories, and even to improve communication between teams.

Is it gerkin or gherkin?

The correct spelling is “gherkin” — “gerkin” is a common misspelling. It refers to a type of small cucumber that is often pickled. Some people call it cucumber, and others call it Gherkin. They mean the same 🙂

As for where Gherkin syntax got its name, you’ll have to ask the team behind the Cucumber testing framework. They developed Gherkin to provide a clear, consistent way to write test scenarios in plain language.

Understanding Gherkin’s syntax

So, how does Gherkin actually work? There are few things that are simpler than Gherkin. It uses the following keywords:

• Scenario: Define the scenario
• Given: Elaborate on the scenario
• When: Combined with the scenario, you describe the action
• Then: Define the result of the action in the given scenario
• And: Add details to scenarios, actions, and results

The most basic Gherkin syntax uses the Given-When-Then (GWT) format. Given the context for a scenario, when something happens to start the scenario, then it has a certain result. Simple, right?

Let’s take an example of searching for apartments to rent:

• Scenario: user with save filters
• Given that the user is searching for a new place
• And the user has defined the favorite filters
• When the user searches for apartments
• Then a list of matching options is presented, sorted by the most matching ones

Note that you can add “and” as a condition to complement the scenario. This scenario is simple to understand yet easy to translate into software engineering.

---

Over 200k developers and product managers use LogRocket to create better digital experiences

Learn more →

---

How to use Gherkin with product management

You may read all the above and ask, “Why should I bother?” This question depends a lot on your scenario. Product management doesn’t have anything that’s one-size-fits-all. That’s why you need to understand your business dynamics.

• The farther software engineers are from the business, the more Gherkin makes sense
• The more software engineers need guidance, the more Gherkin helps
• The clearer backlog items need to be, the more Gherkin is on your side

The above enables you to understand when to use it. I won’t enter into the nitty-gritty of backlog management here. That’s a talk for another coffee. Instead, let’s talk about how you can use Gherkin in product management.

My take is simple:

• Product managers need to provide context and why that matters
• Software engineers with product designers and product managers find solutions for the problem
• Software engineers figure out how to implement the most suitable solution

There are many ways of providing context. The most common ones are:

1. Verbally — You share all the context with verbal communication. Chances are people forget that a few minutes afterward
2. Written — You use your best writing skills to share context, but if you write a memo, software engineers might not read it

Given the continuous misunderstandings in a business context
When product managers say something
And misunderstandings take over
Then Gherkin comes in handy because it’s simple
And creates an elegant bridge between business and tech

We’ve just used Gherkin to describe a real scenario 🙂

Circling back to the story I started earlier, I used to write acceptance criteria before sharing the user stories with software engineers. When I did this, they complained about the format and level of detail. Then, I started writing together with them. Although that improved, we still ran in circles.

Once I introduced Gherkin, I could give the context with my own words, and together we wrote down the scenarios. Contrary to what I initially thought, it accelerated our refinement and understanding.

Gherkin and behavior-driven development (BDD)

Behavior-driven development, aka BDD, is an agile way of developing software. Mainly, it focuses on understanding user behaviors and how they relate to the experience of interacting with the application.

BDD has user behavior as the core of everything. And Gherkin is an excellent representation of it because it allows us to describe the behavior, action, and result. Let’s take ChatGPT as an example:

Scenario: eloquently asking for a salary increase
Given the user has ChatGPT open
When the user requests ChatGPT to write a speech to convince the manager to give a 15 percent salary increase
Then ChatGPT will produce a persuasive, expressive message

By the way, I just tried that, and it looked like this:

Gherkin with BDD is a powerful combination to bring clarity and focus on users’ behaviors. This approach ensures predictable results and avoids confusion.

Pros and cons of Gherkin syntax

As with everything in life, you’d have advantages and disadvantages. Let me help you understand them.

Advantages of Gherkin language

If you start working with Gherkin, you will for sure benefit from the following:

• Better context understanding
• Focus on user behavior and actions
• Reduce rework due to confusion
• Higher test coverage (software engineers can reuse the syntax to automate tests)

Disadvantages of Gherkin language

Yet, not everything about Gherkin is smooth. Gherkin may bring some setbacks:

• Only doing what’s written diminishes creativity
• Extensive wording discussions instead of progressing
• Tendency to assume scenarios are always right and failing to check those assumptions

Best practices with Gherkin and BDD

If you’ve opted to use Gherkin, the following practices will help you deliver better results:

• Combined expertise — Together, the product manager, software engineer, and product designer write scenarios. This is important to have different perspectives and create more concise scenarios
• Don’t limit it to scenarios — Use the scenarios as starting points but embrace learning during the journey. You will uncover opportunities, share them, and develop new scenarios
• Accept mistakes — Some scenarios will turn out wrong, learn from them and adapt to other scenarios accordingly
• Don’t ignore assumptions — With BDD, we tend to think we know more than we do. Name assumptions, test them, and develop scenarios based on evidence, not opinions

Remember that Gherkin is meant to be a helpful tool, not the ultimate answer. Try it out and follow these best practices to see if it’s effective for your team.

Conclusion

Let’s quickly summarize what we discussed in this article:

• What is Gherkin? Gherkin is a plain-text language with a simple syntax that’s often used in behavior-driven development (BDD)

• How does Gherkin work? Gherkin syntax follows the Given-When-Then (GWT) format to describe a scenario, its context, and its outcomes. You can add other simple keywords, like “Scenario” or “And”, to provide more detail:
  • Scenario — Brief description of the scenario
  • Given — More context for the scenario
  • When — Describe the action that starts the scenario
  • Then — Define the result of the action
  • And — Add details to any of the other keywords

• Why use Gherkin in UX and PM? Gherkin’s simple syntax can help improve collaboration and communication between team members. You can use it to write clearly defined acceptance criteria, test cases, user stories, and more, reducing confusion and allowing different perspectives to be heard

Gherkin and BDD are powerful because they provide guidance and clarity while reducing confusion. Yet, they may limit teams to execution. If you opt to use Gherkin and BDD, create space for innovation. Otherwise, you may fall prey to the build trap.

As stated in the Agile Manifesto in 2001, “Individuals and interactions over processes and tools.” Focus on collaboration instead of getting obsessed with tools. I’ve had many benefits with Gherkin but have seen teams obsessed with that and becoming blind to opportunities around them.

Remember that you’re the driver.

Gherkin and BDD should act as a tool to empower you to create value faster, but that should by no means limit teams’ creativity.

Featured image source: IconScout

LogRocket generates product insights that lead to meaningful action

LogRocket identifies friction points in the user experience so you can make informed decisions about product and design changes that must happen to hit your goals.

With LogRocket, you can understand the scope of the issues affecting your product and prioritize the changes that need to be made. LogRocket simplifies workflows by allowing Engineering, Product, UX, and Design teams to work from the same data as you, eliminating any confusion about what needs to be done.

Get your teams on the same page — try LogRocket today.