Acceptance Criteria: Given When Then Syntax

I like pickles, and I like weird names. So what’s not to like about the Gherkin syntax? The given when then format can help ensure a team delivers value.

What is Given When Then?

Given When Then is a syntax used to specify acceptance criteria in a language easily understood by non-technical folks.

Aslak Hellesøy developed the syntax to support his testing tool, Cucumber. His wife chose the odd vegetable-based name, and Aslak went with Gherkin to align the theme. I love this because I’m a total sucker for inside jokes.

Technically, Cucumber was a tool created to support Behavior Driven Development (BDD), and Gherkin was a syntax designed for Cucumber. Although behavior driven development is an exciting topic, deep diving into it is outside this post’s scope.

I find the Gherkin syntax to be an indispensable template for specifying acceptance criteria. User stories have various standard templates you can use to define requirements, but there are few techniques dedicated to defining acceptance criteria.

I’m not a fan of reinventing the wheel. Since someone has already developed a tool to help me think about clearly and succinctly describing my acceptance criteria, I will use it. Who doesn’t appreciate a simpler life?

Given When Then Examples

GIVEN that the dishwasher is empty
WHEN there are more than zero dishes stacked up on the counter
THEN put all the dirty dishes in the dishwasher

A prior scenario to this one might describe what should happen if the dishwasher isn’t empty.

GIVEN the dishwasher is full
WHEN there are more than zero dirty dishes on the counter
THEN empty the dishwasher

At this point, our first scenario should kick in and leave us with a clean kitchen counter. Or will it? What if all of the dirty dishes won’t fit in the dishwasher?

Well, we can introduce the BUT keyword.

GIVEN that the dishwasher is empty
WHEN there are more than zero dishes stacked up on the counter
THEN put all the dirty dishes in the dishwasher
BUT don’t over-fill the dishwasher

This might just be a Miranda thing, but somewhere over the years, I’ve started to capitalize the keywords: GIVEN, WHEN, THEN, BUT, and AND. This is a personal preference, and in my opinion, it helps my mind follow the flow better.

Although the keywords mentioned earlier cover most of the syntax - especially in its usage for specifying acceptance criteria for user stories- there are some additional features that you might find helpful. For instance, the example below repeats AND a lot.

Given you have cream cheese
AND you have sugar
AND you have sour cream
AND you have vanilla extract
AND you have salt
AND you have eggs
AND you have a graham cracker crust
WHEN you’re craving an awesome dessert
THEN make a cheesecake

If you’re the person that must type all these ANDs while the rest of the team stares with their judging eyes, you might appreciate using the * which servers as a bullet point in Gherkin syntax.

Given you have cream cheese
> * you have sugar
> * you have sour cream
> * you have vanilla extract
> * you have salt
> * you have eggs
> * you have a graham cracker crust
WHEN you’re craving an awesome dessert
THEN make a cheesecake

You can learn more about Gherkin syntax on the cucumber website.

Given When Then Syntax Benefits

Forces Critical Thinking

I might sound a bit cruel here, but in my experience, getting clear requirements from stakeholders has been like pulling teeth. Sometimes, people in technical positions are more inclined toward critical thinking. I’m not trying to imply that everyone else in the world is dumb, but there is a particular thinking pattern required to develop working software, and not everyone has that skill.

Using a template like GIVEN-WHEN-THEN can quickly kick people into the correct head space to define acceptance criteria to facilitate delivering more customer value. But the syntax isn’t so specialized as to alienate a non-technical stakeholder. The outcome of a discussion with a customer can be documented in this syntax and easily converted to code later.

Simply showing someone an example of a specification written in this format should be enough to get them primed for collaboration without a ton of extra explanation or setup.

Illuminates Edge Cases

If you look at a scenario written in this format, it draws your attention to the elements that are setting the stage. The phrase “GIVEN the dishwasher is empty” instantly makes you think about what must be true for the rest of the statements to apply.

The opposite is also true. Your next thought will likely be, “What happens when the dishwasher isn’t empty?” If this avenue is relevant, the team can easily make it into a different scenario that describes what should happen in that circumstance.

It’s common for stakeholders to naturally migrate toward the “happy path” or what they expect to happen without considering less-than-ideal branching paths. The Given-When-Then Structure makes it easy to scan back through your GIVENs and check whether there is a branching path that the team missed.

Ensures Succinctness

Anyone reading this blog knows I tend to be a little wordy. I’m not the only person who suffers from this affliction.

The structure afforded to us by the Gherkin syntax can help to compel team members to be more succinct in their specifications. Straightforward specifications reduce waste triggered by the need for developers to re-read the details and boil them down to the key points.

If the end result of having the ingredients on hand is that you’ll make a cheesecake, rambling on about their potential location isn’t super relevant to the decision. The milk might often hide the cream cheese, and your grandmother’s chickens may lay the best eggs, but these facts shouldn’t obfuscate the acceptance criteria.

Easy to Understand

The syntax utilizes natural language and thus is simple enough that most people should be able to pick it up clearly. In this short post, I’ve covered the majority of its features. A training class isn’t required, and we all don’t have to read the same book to understand the format.

It puts me in the mind of ELI5. Start basic with something a five-year-old can understand. If a five-year-old understands it, you’ve removed any significant ambiguity between the stakeholders and the development team regarding what the user story needs to accomplish.

As a bonus, it’s easier to transform effective acceptance criteria into implementation details once we reach the development stage.

Documentation Jumpstart

This quote is one of my favorites from Stephen King’s book On Writing:

“You can approach the act of writing with nervousness, excitement, hopefulness, or even despair—the sense that you can never completely put on the page what’s in your mind and heart. You can come to the act with your fists clenched and your eyes narrowed, ready to kick ass and take down names. You can come to it because you want a girl to marry you or because you want to change the world. Come to it any way but lightly. Let me say it again: you must not come lightly to the blank page.”

―Stephen King (Foreward)

I can’t emphasize enough the anxiety I have when I first approach a blog post without an accurate idea of the structure of what I plan to write about. I procrastinate something awful. Regardless of the task, it’s hard to start from scratch.

I can say the same about detailing the success conditions of a user story. Well-written acceptance criteria are hard to come by; however, the GIVEN-WHEN-THEN formula provides a jump start to get creative juices flowing. In a way, it’s like mad libs for user requirements, and all we have to do is fill in the blanks.

Given When Then Syntax Issues

Exceptions to the Format

I’ve encountered user stories that don’t sound right when squashed into a standard template. Rearranging what you need to say to follow a structure can sometimes interfere with interpretation. Use this template with a grain of common sense. If it provides value, then, by all means, use it, but if it makes the process harder and we can’t offset that struggle by equal or greater value, then this format may not be the best solution. The syntax may not be a good fit for every situation.

Simple is Subjective

One of the main benefits of this template is based on the assumption that it’s easy for everyone to understand. However, even this simple syntax will be beyond the understanding of some individuals.

I once worked with a development team tasked with building a new product to replace an antiquated process. The first step involved meeting with the process subject matter expert to define the business rules. We already knew our stakeholder didn’t have a technical bone in her body and thus assumed this template would be a perfect solution to bridge the communication gap.

As we started working through scenarios, the customer became increasingly frustrated. She complained that writing these statements in this format was too close to writing code, and she insisted that she wasn’t a programmer.

No one technique will work for all people. If you force a particular template onto a situation that isn’t valuable for everyone, you’re likely to get some unhappy people. So keep this as a tool in your tool belt, but be open to recognizing when it’s not the best solution.

Silly Venerability

If you’re collaborating with someone that tends to be more uptight and proper, a technique like this can make you feel silly. It can be challenging for someone to admit that he doesn’t fully understand a topic without using such a basic technique. You might feel a bit like you’re taking meeting notes using a crayon.

In my experience, however, I’d caution you against avoiding this exercise out of fear that someone will find it silly. Nine times out of ten, the stakeholder that rolls their eyes because they think you’re incompetent will be the first to catch on to the value of this exercise. The process will ferret out edge cases that would have otherwise gone unnoticed. The attention to detail now will pay off dividends in the future when we can avoid what would have otherwise been massive amounts of rework and repeated discussions.

Works Consulted

• BDD Tool Cucumber is 10 Years Old: Q&A with its Founder Aslak Hellesøy
• The Cucumber Book: Behaviour-Driven Development for Testers and Developers
• Gherkin Syntax
• BDD in Action: Behavior-driven development for the whole software lifecycle

TLDR

If you like pickles and trying to get everyone on the same page, give Gherkin a shot in your next requirements-gathering session. Don’t expect it to magically solve the complexities of the problems you need to solve, but it might help to overcome ambiguity and pluralistic ignorance.