What’s Gherkin For?

When we build software for people (let’s call them stakeholders), it’s notoriously difficult to figure out exactly what they want us to build. In his famous essay, No Silver Bullet [Bro95], Fred Brooks says:

“The hardest single part of building a software system is deciding precisely what to build.”

We’ve all worked on projects where, because of a misunderstanding, code that we’d worked hard on for days or more had to be thrown away. Better communication between developers and stakeholders is essential to help avoid this kind of wasted time. One technique that really helps facilitate this communication is the use of concrete examples to illustrate what we want the software to do.

Concrete Examples

By using real-world examples to describe the desired behavior of the system we want to build, we stay grounded in language and terminology that makes sense to our stakeholders: we’re speaking their language. When we talk in terms of these examples, they can really imagine themselves using the system, and that means they can start to give us useful feedback and ideas before a line of code has been written.

To illustrate this, let’s imagine you’re building a credit card payment system. One of the requirements is to make sure users can’t enter bad data. Here’s one way of expressing that:

Customers should be prevented from entering invalid credit card details.

This is an example of what agile teams often call acceptance criteria or conditions of satisfaction.^[5] We use the word acceptance because they tell us what the system must be able to do in order for our stakeholders to find it acceptable.

The previous requirements statement is useful, but it leaves far too much room for ambiguity and misunderstanding. It lacks precision. What exactly makes a set of details invalid? How exactly should the user be prevented from entering them? We’ve seen too many projects get dragged into the tar pit^[6] by these kind of worthy but vague statements. Let’s try illustrating this requirement with a concrete example:

If a customer enters a credit card number that isn’t exactly 16 digits long, when they try to submit the form, it should be redisplayed with an error message advising them of the correct number of digits.

Can you see how much more specific this second statement is? As a developer implementing this feature, we know almost everything we need to be able to sit down and start working on the code. As a stakeholder, we have a much clearer idea of what the developer is going to build.

In fact, a stakeholder reading this might point out that there are certain types of cards that are valid with less than 16 digits and give us another example. This is the power of examples: they stimulate our imagination, enabling us to explore and discover edge cases we might otherwise have found much later.

By giving an example to illustrate our requirement, we’ve turned an acceptance criterion into an acceptance test. Now we have something unambiguous we can use to test the behavior of the system, manually or with an automated test script.

Try This

Think about a feature you’re working on right now or have worked on recently. Can you write down three concrete examples of the behavior needed for that feature to be acceptable?

Executable Specifications

Another advantage of using concrete examples is that they’re much easier to validate against the running system than vague requirement statements. In fact, if we’re neat and tidy about how we express them, we can get the computer to check them for us. We call this automated acceptance testing.^[7]

The challenge with writing good automated acceptance tests is that, for them to be really effective, they need to be readable by not only the computer but also by our stakeholders. It’s this human readability that allows us to get feedback about what we’re building while we’re building it. This is where Gherkin comes in.

Gherkin gives us a lightweight structure for documenting examples of the behavior our stakeholders want, in a way that’s easily understood both by the stakeholders and by Cucumber. Although we can call Gherkin a programming language,^[8] its primary design goal is human readability, meaning you can write automated tests that read like documentation. Here’s an example:

One interesting feature of Gherkin’s syntax is that it is not tied down to one particular spoken language. Each of Gherkin’s keywords has been translated into more than forty different spoken languages, and it is perfectly valid to use any of them to write your Gherkin features. No matter if your users speak Norwegian or Spanish, med Gherkin kan du beskrive funksjonalitet i et språk de vil forstå. (Gherkin lets you to write your features in a language they will understand.) Tocino grueso! (Chunky Bacon!) More on that later.