 |
From Writing Great Specifications by Kamil Nicieja
This article dives head-first into writing specifications using Specification by Example and Gherkin. |
Save 37% on Writing Great Specifications. Just enter code fccnicieja into the discount code box at checkout at manning.com.
Writing our first Gherkin scenario
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
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 statement
Feature: Scheduling
Feature is Gherkin’s word for indicating that a new specification has begun—what follows is a name of the feature being documented.
Below the feature line, you can add an additional description of the feature. It’s expected to describe the business value of this feature or to provide any additional information that will make the feature easier to understand. In this book, we call it a specification brief.
 |
Specification brief
Specification briefs can contain important pieces of information—they answer the question for why the specification was written in the first place. Who is the feature being made for? Why do they need it? Their role is to remind you to come up with good answers. |
But 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 should inform the reader where other scenarios can be found.
Listing 2 A feature statement 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. ❶
❶ The specification brief
Scenario
In Chapter 1, I told you that Gherkin captures behavioral requirements. Behavioral requirements are formed as stories about how users behave when they interact with the system. In Gherkin, these stories are called scenarios. In this section, we’re going to start 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 ❶
❶ The name of our first scenario
In our example, the Scenario statement we added in the listing above lets both the reader and the automation framework know that a new scenario begins below.
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 that we’re going to discuss throughout the book—for example, providing definitions for domain-specific concepts.
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 what the purpose of the scenario is. 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 may 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. We’ll talk more about this in Chapter 4 where we’ll cover all the details regarding the template.
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 must be some users who will be able to do it—so some 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 ❶
❶ A Given we added to the scenario
But that’s a tad vague, isn’t it? All apps have users. And pretty much anyone can be a user. 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 ❶
❶ A more specific Given
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 a team member called Mike ❶
❶ A Given with a real person
Users play key roles in scenario, and it’s a good practice to use unique, real names for two reasons.
-
When two users appear in a single scenario, calling them team member 1 and team member 2 sounds awkward.
-
Real names facilitate empathy. In one of my projects, I called the user in most of my scenarios a Simona. Every time I wrote a scenario, I imagined she’s anxious to get her work done as fast as she can today, because she left a sick child home. I wondered whether there’s anything more I can do to make her work easier. We’ll talk about that more in Chapter 4.
Because of the second bullet point, we’re going to stick with our Mike even though there’s only one person participating in our scenario. Hello, Mike. Do you like Gherkin? (I bet he does. It’s the sole reason we brought him into existence.)
Whens
Givens create the context in which the rest of the scenario takes place. We should keep the momentum going and specify what the main action of our scenario should be. And, because they describe the key action the user performs, that’s the perfect job for a new When. 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 a team member called Mike ❶
When Mike chooses 2 PM as a start time for his meeting ❷
❶ The prerequisite needed for the main action to happen
❷ The main action of the scenario
As you can see, we’re aiming for as concrete an example as possible: apart from the users we introduced in the previous step, we’ve added specific hours.
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 adopt these names for their classes and copywriting, because they wouldn’t have to invent their own.
Beware that adopting terms from a scenario makes sense only when it includes real world examples provided by business stakeholders or customers. Introducing artificial terms always widens the communication gap instead of bridging it.
Every scenario should preferably have only a singular When, because doing so makes scenarios much clearer and easier to read. Mixing Whens only creates tangled, unclear designs. You can read more about that in Chapter 4 where I talk about user tasks and choosing the right abstraction level for your scenarios.
Thens
An action without any 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 a team member called Mike ❶
When Mike chooses 2 PM as a start time for his meeting ❷
Then he should be able to save his meeting ❸
❶ The predicate
❷ The main action
❸ The consequence of the action
Thens describe consequences. In our case, choosing a valid start time for a meeting results in successfully creating the meeting. 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 created 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. It’s 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, check out the book on liveBook here and see this Slideshare presentation.