Writing Your First Gherkin Scenario

This article was excerpted from Writing Great Specifications

Maybe you’ve heard of how Gherkin and Specification by Example works. Perhaps you’ve heard about how product design conversations captured in Gherkin become automated tests, and how automation keeps executable specifications up to date. Let’s go through the basics of writing a simple executable specification from scratch. We are going to work with an example of a calendar application for teams, similar to Google Calendar. Every calendar application must allow teams to schedule meetings — to keep things simple, that’s the one and only thing we’re going to specify today.

Figure 1. You could imagine our application as a simpler clone of Google Calendar, Microsoft Outlook, or really any other popular scheduling software

Feature

It’s time to write some Gherkin. We’re going to go through a step-by-step tour of writing your first scenario. To begin, create an empty text file in any text editor of your choice.

Every Gherkin feature file starts in a similar manner.

Listing 1 A feature line

Feature: Scheduling

Feature is Gherkin’s word for indicating that a new specification has begun — what follows is the name of the feature being documented. Conventionally, every feature file consists of a single feature in order to encourage writing many small files rather than a few large specifications.

Below the feature line, you can add an additional description of the feature. This is generally used to describe the business value of this feature, or to provide any additional information that will make the feature easier to understand. Let’s call it a specification brief.

Specification briefs can contain important pieces of information — they answer the question of why the specification was written in the first place. Who is the feature being made for? Why do they need it?

For the time being let’s keep our feature file simple. Given our scope, we’re only going to specify one or two scenarios. We want to inform the reader where other scenarios can be found.

Listing 2 A feature line followed by a description

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the “meetings” folder in the

specification suite.

From the point of view of Gherkin’s syntax, the first line is the most important, because the Feature cannot ever be changed. The spaces in front are important as well, because the spaces tell Cucumber what the file’s structure is. There are no strict rules or limitations regarding vertical spacing between the first line and the specification brief.

Scenario

We know that Gherkin captures behavioral requirements. Behavioral requirements come in the form of stories about how users behave when they interact with the system. In Gherkin, these stories are called scenarios. Let’s get started writing our first scenario.

Listing 3 Our first scenario

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting

In our example, the scenario line we added in the above listing, which lets both the reader and the automation framework know where the new scenario starts.

If a scenario needs additional elaboration, you can place any amount of free-flowing text between the Scenario line and the first Given. It’s similar to the specification brief and that’s why we call it a scenario brief. There are multiple ways to use the free-flowing space — for example, providing definitions for domain-specific concepts, which deals with living documentation.

Every scenario should:

define context (the Givens)

describe an event that occurs within the system (the Whens)

ensure that expected outcomes take place (the Thens)

The sequence is called the Given-When-Then template.

The Givens explain what needs to happen so we can watch the rest of the scenario take place. The Whens neatly organize the template around a single behavior of the system, so a reader doesn’t have to wonder at the purpose of the scenario. The Thens clarify the consequences of taking that action.

The Given-When-Then template is a simple, yet powerful tool. It often works as a harmonious system. A slight change anywhere could influence a new change elsewhere. Givens, Whens and Thens influence each other, but sometimes they force entire scenarios to change — and when scenarios change, sometimes entire specifications must change as well.

Givens

Ah, the Givens…Givens answer a single question: what are the prerequisites that allow the scenario to happen?

For example, when a scenario’s main action is (like in our case) creating a meeting, there have to be some users who will be able to take part, i.e. at least one user account must have been created first.

Listing 4 Our first Given

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting Given a user

You can see that there are two more spaces before our Given. Scenarios require additional indentation because it helps Cucumber understand which Givens, Whens, and Thens belong to which scenarios.

Given a user… that’s sounds vague, doesn’t it? All apps have users. First, the naming doesn’t explain anything. Second, we’re working extremely hard to make our application unique; the specification should reflect that, too.

Listing 5 Our first Given reworked

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting Given a team member

Better! Now we can at least see that it’s collaborative software for teams. A team member sounds a bit abstract, though — and software should be made for real people.

Listing 6 Our first Given reworked for the second time

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting Given Mike, a member of our team

Users play key roles in scenarios, and it’s a good practice to use unique, real names. Let me give you one simple example:

Let’s say that two users appear in a single scenario. Calling them team member 1 and team member 2 would sound awkward, wouldn’t it? So that’s why we’ll have a Mike — because Mike doesn’t sound awkward, and when things aren’t awkward, more people read and understand them. Hello, Mike. Do you like Gherkin? (I bet he does. It’s the sole reason we brought him into existence.)

When

Givens create the context in which the rest of the scenario takes place. Let’s keep our momentum going and specify what the main action of our scenario should be. That’s where Whens come in — they describe the key action the user performs. Let’s add one to our scenario.

Listing 7 Our first When

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting Given Mike, a member of our team

When Mike chooses 2 PM as a start time for his meeting

As you can see, we’re aiming for as concrete an example as possible — apart from the user we introduced in the previous step, we’ve added a specific time. You can also see that I aligned the second step to the right so the word When ends at the same place where Given does. This is a community convention that you will see in many feature files, but it isn’t obligatory.

Please note that the scenario has already introduced some simple terms into the ubiquitous language of our product — a meeting, a team member, a start time. If programmers or designers were to read it, they would naturally adopt these names for their classes and copywriting, because they wouldn’t have to invent their own. Unfortunately, introducing artificial terms almost always widens the communication gap instead of bridging it.

Every scenario should preferably have only a singal When, because it makes scenarios clearer and easier to read.

Thens

All this action without an outcome is wasted! The part of the Given-When-Then template that asserts the outcomes is the Then part — so why don’t we add it to our scenario?

Listing 8 Our first Then

Feature: Scheduling Because scheduling is a huge functionality, this

specification file describes only the most important

high-level scenario.

You can find more detailed scenarios in the rest

of the files inside the "meetings" folder in the

specification suite. Scenario: Creating a meeting Given Mike, a member of our team

When Mike chooses 2 PM as a start time for his meeting

Then he should be able to save his meeting

Thens describe consequences. When we choose a valid start time for a meeting, a meeting is created. A Then is usually a concrete representation of the rule your criteria try to enforce. The representation is usually a change in the system. For example, it may be something new that was created — like Mike creating his first meeting — but it may also be something that was removed or rephrased.

The main difference between the scenario above and the acceptance criteria you usually see is that our scenario seems much more personal. That is because:

acceptance criteria are the abstract rules of the system; scenarios tell stories about people who use the system according to these rules

human beings discuss and remember stories much better than abstract rules

By adding a Then, we’ve arrived at our full Gherkin specification — and in only 8 short steps!

Try Writing Great Specifications for yourself!

If you liked what you read in this article and want to read more, go ahead and download the free first chapter of Writing Great Specifications and see this Slideshare presentation for a discount code!