How to write scenarios using Gherkin language

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 of chat.

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

What is Gherkin language?

Gherkin is a plain-text language with a simple structure. It enables a concise description of test scenarios and examples to illustrate business rules in real-world domains.

Some people call it cucumber, and others call it Gherkin. They mean the same 🙂

The goal is to give business scenarios a clear context 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.”

Understanding Gherkin’s syntax

A few things can be simpler than Gherkin. It uses the following keywords:

• Scenario: define the name of the scenario
• Given: that’s how you elaborate on the scenario
• When: combined with the scenario, you describe the action
• Then: the last part defines the result of the action in the given scenario
• And: to add details to scenarios, actions, and results

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.

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. Now, let’s talk about how you can combine Gherkin with 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 won’t read it

Given the continuous misunderstandings of the business context
When product managers say something
And misunderstandings take over
Then comes Gherkin 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, I used to write acceptance criteria before sharing the user stories with software engineers. Yet, 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: beautifully asking for a salary increase
Given the user has the ChatGPT open
When the user requests ChatGPT to write a speech to convince the manager to give a 15 percent salary increase
Then ChatGPT drops a well elaborate message

By the way, I’ve just tried that, and it looked like this. Would that work?

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

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

Conclusion

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