Writing better user stories with Gherkin and Cucumber

Writing automated unit tests for the software we build can seem like a large amount of groundwork without a clear payoff. However, the long-term benefit to your team’s health, happiness, and velocity dwarfs the upfront investment. Among many other benefits, automated testing catches bugs, enables continuous deployment, and makes it easier for developers to chip in on unfamiliar code.

Cucumber is a tool that allows us to create automated software tests in an easy to write, easy to read way. Although many product teams struggle to get automated testing off the ground (perhaps never having heard of tools like Cucumber), nearly all of them have unwittingly dabbled with one of its key components — Gherkin.

When used judiciously, writing acceptance criteria in Gherkin form is a great way for teams to define and agree on what ‘done’ means for the features they build. Despite its simplicity, Gherkin is a very nuanced language. With that nuance comes a lot of confusion about what separates a statement that is written well from one that is written poorly, especially for people new to Gherkin.

In isolation, Gherkin’s quirks can seem confusing, but when viewed in the context of automated Cucumber tests, those subtleties make a lot more sense. This article goes over how Gherkin and Cucumber fit together so that you can see how to use Gherkin more effectively today. By the end of this article, you will learn how a full Gherkin + Cucumber implementation works and how building a library of well written Gherkin scenarios paves the way for automated testing.

Gherkin

Gherkin is a Domain Specific Language for writing acceptance criteria that has five main statements:

1. Scenario — a label for the behavior you’re going to describe
2. Given — the beginning state of the scenario
3. When — a specific action that the user takes
4. Then — a testable outcome, usually caused by the action in When
5. And — this continues any of the other three operators

Together these statements describe all of the actions that a user must take to perform a task and the result of those actions.