Behavior-driven development (BDD) practices can help your teams build better software by making them carefully specify the product’s behaviors using plain-language examples. And whether you're seeking better collaboration through "three amigos" meetings or wanting to automate better using a framework such as Cucumber, one language rests at the center of the BDD movement: Gherkin.
On the surface, Gherkin looks easy—just write some steps to describe the desired behavior. However, I’ve seen several teams struggle with writing Gherkin well. Beginners often get writer’s block, or they write scenarios that can’t easily be automated. Sometimes, ambiguity leads people to interpret steps in different ways. Other times, people provide too much detail in their steps, which makes scenarios hard to understand. BDD even gets a bad rap due to frustrations with Gherkin.
Writing good Gherkin may be challenging, but it certainly isn’t impossible. Here are four rules that will help you to write readable, automatable, scalable Gherkin.
1. Gherkin's Golden Rule
Gherkin’s Golden Rule is simple: Treat other readers as you would want to be treated. More specifically, write feature files so that everyone can intuitively understand them. Good Gherkin should improve team collaboration by clarifying behaviors you want to develop. When Gherkin is tough for others to read, teams can’t develop good behaviors.
Let’s say your team is developing a website for a shoe store. Consider the following scenario:
Scenario: Shoes
Given I want shoes
When I buy shoes
Then I get them
This scenario is ultra-declarative because it doesn’t provide enough information about the desired behavior. It’s too vague. What shoes? How are they purchased? How will you verify the purchase? It’s also not automatable because the steps are not procedural. The fact that the narrator wants shoes is part of the user story, not the specification. The scenario also lacks accountability because it omits any clear conditions for success. Typically, product owners are more likely to write ultra-declarative scenarios such as this because they aren’t familiar with automation.
Now, consider the opposite extreme:
Scenario: Purchase shoes through the app
Given my username is "jessica8494"
And my password is "PleaseDontPutSecretsInGherkin"
When I navigate the browser to "www.shoestore.com"
And I enter my username into the "Username" field
And I enter my password into the "Password" field
And I click the login button
And I wait "10" seconds
Then the Shoe Store home page is displayed
And the title banner contains the text "Shoe Store"
And the shopping cart is empty
When I click the search bar
And I type "red pumps" into the search bar
And I click the search button
And I wait "30" seconds
Then the search results page is displayed
And the search results page shows "10" results per page
And ...
This scenario is ultra-imperative because it provides too much detail. All the steps name manual, low-level interactions such as clicking buttons and waiting for seconds to pass. They overwhelm the reader with a wall of text that obfuscates rather than clarifies the value of this scenario. You can automate each step, but collaboration will be tough.
If you were on this team, would you want to be assigned either of these scenarios? Certainly not, since neither helps to build the desired behavior. Here’s how to write these:
Scenario: Add shoes to the shopping cart
Given the shoe store home page is displayed
When the shopper searches for "red pumps"
And the shopper adds the first result to the cart
Then the cart has one pair of "red pumps"
This scenario has declarative, descriptive steps. The steps strictly follow a given-when-then order that clearly shows the setup, the interaction, and the verification of the desired behavior. The scenario uses “red pumps” as a concrete example to help the reader better understand the scenario. The scenario is concise, yet unambiguous. It’s a much better scenario than the others.
If you aren’t sure if your scenarios are too declarative or too imperative, refer to Gherkin’s Golden Rule. What kind of scenario would you want to read?
2. The cardinal rule of BDD
The cardinal rule of BDD is a one-to-one rule: One scenario should cover exactly one single, independent behavior. Focusing on one behavior at a time has several benefits:
- Collaboration: More focus and less confusion
- Automation: Each test failure points to a unique problem
- Efficiency: Less complex work makes for faster cycle times
- Traceability: 1 behavior → 1 example → 1 scenario → 1 test → 1 result
- Accountability: Teams cannot hide or avoid behaviors
Thankfully, it’s easy to spot a scenario that covers more than one behavior. Consider this scenario:
Scenario: Simple product search
Given the shoe store home page is displayed
When the search phrase "red pumps" is entered
Then results for "red pumps" are shown
When the user searches for images from the results page
Then image results for "red pumps" are shown
This scenario covers two separate behaviors: searching for shoes, and searching for images of shoes. Each when-then pair denotes a unique behavior. Whenever a scenario has more than one when-then pair, it inherently covers more than one behavior. Thankfully, splitting scenarios is easy:
Scenario: Simple Web search
Given the shoe store home page is displayed
When the search phrase "red pumps" is entered
Then results for "red pumps" are shown
Scenario: Simple Web image search
Given shoe store search results for "red pumps" are displayed
When the user searches for images from the results page
Then image results for "red pumps" are shown
You can capture the stopping point for the first scenario as a new given step for the second scenario. In this way, the second scenario focuses only on its unique behavior. You can also use automation to try to optimize this given step by taking shortcuts such as a direct link.
3. The unique example rule
Sometimes, less is more, so don’t include unnecessary examples. Focus instead on unique equivalence classes. Testing “all the things” might sound tempting, but that wastes precious time. Instead, test the most important things, and avoid testing duplicate things.
Consider the following scenario:
Scenario Outline: Simple product search
Given the shoe store home page is displayed
When the search phrase "<phrase>" is entered
Then results for "<phrase>" are shown
Examples: Shoes
| phrase |
| red pumps |
| sneakers |
| sandals |
| flip flops |
| flats |
| slippers |
| running shoes |
Scenario outlines run the scenario, one for each row in the examples table, so this scenario outline would run seven times. If a typical web UI test takes one minute, then each run will add a lot of time to the whole test suite. All of these examples just cover different types of shoes. Arguably, “shoes” could be an equivalence class, so testing different types of shoes may not be worthwhile. Always carefully consider the examples chosen.
4. The good grammar rule
Language matters, so write as though your high school English teacher will be grading your Gherkin. Behavior scenarios are meant to be readable and expressive. Steps are meant to be reusable. Poor grammar, misspellings, and inconsistent phrasing can ruin the benefits of behavior specification. Scenarios can become confusing, and team members could use steps out of context.
One of the biggest language problems with Gherkin is an inconsistent point of view. You can write steps using first-person perspective (“I, me, my”) or third-person perspective (“the user …”). While I strongly favor third-person perspective for Gherkin steps, it is more important for a solution to use one or the other exclusively. Look at what happens when steps mix the point of view:
Scenario: Simple product search
Given I am at the shoe store page
When the user searches for "red pumps"
Then I see web page links for "red pumps"
This scenario is understandable, but looks sloppy. The meaning could also be ambiguous: Am “I” “the user,” or is there a second user? Use one point of view for consistency.
Poor step phrases are another common problem. Your steps should use subject-predicate phrases, just as you would when writing regular sentences. Imagine seeing the following steps:
And image links for "sneakers"
And video links for "sneakers"
Out of context, these steps are ambiguous. Do they click the links? Do they verify the existence of the links? They simply specify a subject, not a predicate. This type of ambiguity can cause problems when a team tries to write and automate new scenarios. Clarify them like this:
And the results page shows image links for "sneakers"
And the results page shows video links for "sneakers"
A third problem I frequently see involves tense: past, present, and future. Each type of step should follow consistent rules within a solution. I recommend the following:
- Given steps should use past or present-perfect tense, because they represent an initial state that must already be established.
- When steps should use present tense, because they represent actions actively performed as part of the behavior.
- Then steps should use present or future tense, because they represent what should happen after the behavior actions.
Practice makes perfect
The rules I’ve shared above should be your guiding principles for good Gherkin. I could give you a bunch of rules about formatting, line length, or word choice, but those are secondary details to good principles. So give it a try, and have fun writing good Gherkin.
Want to learn more about those other rules about Gherkin and BDD? Read my in-depth tutorial.
For more on Gherkin best practices, come to my presentation, "Blasting Off with Good Gherkin," at the TSQA 2020 conference, where I'll cover Gherkin’s syntax and you'll learn how to make Gherkin behavior specs truly great. The conference runs February 26-27 in Durham, North Carolina.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
