Concise Gherkin - How brevity improves BDD scenarios

Ivan Poiraudeau — Tue, 27 Feb 2024 09:42:34 +0000

💡 New to behavior-driven development? It’s a fantastic way to collaborate and produce better documentation.
Here’s an introduction, with details about its dedicated language, Gherkin.

In behavior-driven development (BDD), it’s best practice to keep your scenarios BRIEF, an acronym for:

Business language: The words used in a scenario should be drawn from the business domain.
Real data: Examples should use concrete, real data.
Intention revealing: Scenarios should reveal the intent of what the actors in the scenario are trying to achieve, rather than describing the mechanics of how they will achieve it.
Essential: The purpose of a scenario is to illustrate how a rule should behave. Any part of a scenario that does not directly contribute to this purpose are incidental and should be removed.
Focused: Most scenarios should be focused on illustrating a single rule.

Last year, my team at UpSlide overhauled our user management system through BDD. We noticed that focusing on brevity let us validate several principles at once: our scenarios were becoming more intention revealing, essential and focused.

Brevity reveals scenarios intention

Consider this login step:

Given I visit "/login"
When I enter "Bob" in the "user name" field
  And I enter "tester" in the "password" field
  And I press the "login" button
Then I should be greeted with a welcome message

This scenario is filled with unimportant and brittle implementation details. By prioritizing brevity, we can simplify it to:

When Bob logs in
Then Bob should be greeted with a welcome message

The scenario intention becomes clearer: it emphasizes the need for a welcome message upon login, without getting bogged down in implementation specifics.

Brevity keeps scenarios essential

Here is a scenario about email notifications:

Given Alice's email storage is not full
And Alice is not offline
When Alice sends an email
Then Alice should get notified that the email was sent.

If Alice’s storage is full or if she’s offline, the email indeed cannot be sent so she shouldn’t get notified that it was.

In most email happy paths however, these conditions won’t apply and the reader doesn’t need to know about them.
In the test implementation, we should instead ensure the system under test has enough message storage for Alice and operates as if it’s online. We can then streamline the scenario:

When Alice sends an email
Then Alice should get notified that the email was sent.

Considering storage space and internet connection separately lets us explore other behaviors, each with their own scenarios:

Given Alice's email storage is full
When Alice sends an email
Then Alice should be notified that the email couldn't be sent
And that she needs to free up storage

Given Alice is offline
When Alice sends an email
Then Alice should be notified that the email couldn't be sent
And that she needs to connect to the Internet

Brevity focuses scenarios

Follow this example from Monopoly:

Given the player went over the GO square [A]
When the player falls on a CHANCE square [B]
Then the player should earn 200₩
And the player should take the top CHANCE card

We can see that mixing [A] and [B] in other ways (not going over the GO square, not falling on the CHANCE square) could lead to a combinatorial explosion of scenarios.

Again, noting this scenario lacks brevity leads us to more independent scenarios:

When the player goes over the GO square
Then the player should earn 200₩

When the player falls on a CHANCE square
Then the player should take the top CHANCE card

More on BDD principles

In a process akin to other forms of writings, brevity helps me uncover the core ideas behind the system I’m specifying.

💡 If you’re keen on crafting concise scenarios, I’ve put together a step-by-step kata to assist you:

Check it here!

I didn’t talk much about the two other key principles, Business Language and Real Data. This video by Gáspár Nagy (creator of SpecFlow, a .NET BDD framework) delves deeper into them:

Forem: Ivan Poiraudeau

Concise Gherkin - How brevity improves BDD scenarios

Brevity reveals scenarios intention

Brevity keeps scenarios essential

Brevity focuses scenarios

More on BDD principles