A Formula for Great Gherkin Scenarios (with Given-When-Then Examples)

Gherkin Paves the Way for Automated User Acceptance Testing (UAT)

Domain-specific languages like the Gherkin language express Acceptance Criteria and Acceptance Test Cases in a format that is easy for business stakeholders to use, as well as easy for software programmers to translate into code. Sometimes referred to as “Gherkin User Stories”, technically User Stories express a business need while Gherkin expresses Scenarios which will be used to validate that the User Story is correctly implemented.

Writing Gherkin Scenarios makes automated User Acceptance Testing (UAT) much easier to do. Cucumber, the most widely used open-source software testing framework, supports Gherkin Test Cases written in the Given-When-Then syntax.

What are Given-When-Then Acceptance Criteria and UAT Scenarios

The Gherkin framework is a communication tool that helps business stakeholders to express their wants and needs to the IT team. Many developers believe that Gherkin Acceptance Criteria and User Acceptance Test Scenarios ARE the real user requirements that IT needs.

The terms Acceptance Criteria and Acceptance Tests are often used interchangeably but they are not the same thing. While both words carry the connotation of acceptance, they differ in their definitions:

• User Acceptance Criteria specify the functional and non-functional requirements that need to be met before a Story is considered complete by stakeholders.
• User Acceptance Tests (aka User Story Tests) confirm that the product meets all Acceptance Criteria and functions correctly.

This post will give you the basics of writing Gherkin Scenarios, Gherkin Acceptance Criteria, and User Acceptance Test Cases in GWT form.

If you are not familiar with the User Story model, read my post The Everything User Story Guide: Tips and Tricks for Writing Better Requirements.  For an in-depth how-to, check out my course: How To Write User Stories That Deliver Real Business Value.

Gherkin’s Given-When-Then Trio for Better Specifications

User Acceptance Criteria as well as User Acceptance Test Cases / Scenarios can take many different forms; however, Given-When-Then (GWT) Scenarios have become one of the most wide-spread.

GWT Scenarios follow the Gherkin syntax. They express the business logic using a plain language that everyone in an organization can understand.

The Given-When-Then Gherkin notation is considered one of the best when it comes to making sure that a specification is comprehensive and precise, since its syntax allows us to phrase exactly what we want from business requirements and what we expect as an outcome.

The Given-When-Then Format Is a Template to Guide Your Writing

The GWT clauses are the heart of Gherkin. They provide a means of structuring a sentence to explain the logical progression of an action or event.

Each block of text is written in free-form, which allows you to write them however you want. This makes for a very flexible structure—you can make it as simple or detailed as you would like it to be—but also potentially confusing because there isn’t a strict format.

Look at each clause individually and see how they are used:

GIVEN (setup data such as hardware or data)
In the GIVEN clause, you should express any kind of setup conditions that are necessary for this test to succeed. This encompasses hardware conditions as well as data, files, or records that must have a specific condition for the test to run.

For example, the system must have an available network connection; the file “test.txt” must exist and contain the text “Hello world!”. We recommend against including conditions that are obvious, such as “Given your computer is turned on”, but even that is your choice.

WHEN (action or event that initiates the Scenario)
The WHEN clause defines any actions or events that initiate the Scenario. It is the interaction between a Stakeholder and the system itself.

For example, if you are dealing with a web site the WHEN statement lists the type of user interaction such as “enters value”, “clicks a button”, “submits a form”, etc. However, if you are dealing with an API, for example, the Stakeholder interaction might be “responds to call”. The key is that this clause defines the trigger for the execution of this scenario.

THEN (defines the result or outcome)
Finally, the THEN clause defines the conditions that determine whether or not the test is successful. If the conditions in this clause are met, the software works correctly; otherwise, it fails. This outcome can be a calculated value or any verifiable result.

 GIVEN-WHEN-THEN Examples: The Gherkin Format in Action

GWT Scenarios describe the steps, events, and interactions between a user and the software. The concept of Scenarios is best explained with an example. Here is a simple goal-oriented Story that we created for a training company:

To plan their career development paths, students can see classes they still need to take based on their BASE scores.

In a 3-amigos conversation, we learned that BASE is an acronym for Business Analysis Skills Evaluation — a tool for creating individualized training plans based on a student’s current skills.

As you think about the Tests or Scenarios you need to verify the implementation of this User Story, it becomes clear that there is an obvious one:

Student requests class schedule.

Expressing Business Logic in Given-When-Then Format

As mentioned, the GIVEN clause describes conditions that must be set up for this UAT Scenario to deliver the results that are expected. In other words, you are defining the pre-conditions for this Scenario. If there is more than one pre-condition, use the connector “AND”.

For this User Story to succeed the student must be logged into the Web site, have completed BASE, and have unfinished classes.

SCENARIO: Student has unfinished classes and requests class schedule.
GIVEN Student is logged into the website
  AND Student has completed BASE
  AND Student has unfinished classes

Whereas GIVEN describes the pre-conditions, the WHEN action “Student requests class schedule” triggers this Scenario.

The THEN specifies the outcome meaning the student’s customized training plan is viewable.

SCENARIO: Student has unfinished classes and requests class schedule.
GIVEN Student is logged into the website
  AND Student has completed BASE
  AND Student has unfinished classes
WHEN Student requests class schedule
THEN Student’s customized training plan is viewable

That is the basic concept of Scenarios written in the Given-When-Then Gherkin format. There is, however, one more keyword that can come in handy and save you a ton of work – Background.

Background Statements Save Time in UAT Testing

When you create UAT Test Cases for User Acceptance Testing in the Given-When-Then format, you may think that it is a one-time effort. You build the steps, maybe even write some of the data as a sample, and then before you know it, you have a nice suite of Test Cases.

But then you realize that each of your UAT Scenarios needs to make use of the same “setup” data, and before long, you have to start recreating all that setup for every Test Case.

This repetition can be tedious to type over and over again. Fortunately, there is a simple solution and a great time-saver: the BACKGROUND statement in the Gherkin syntax allows you to define setup criteria that will be used for a group of Scenarios. These setup criteria can be defined once, then used repeatedly by other Scenarios.

All Gherkin statements between the BACKGROUND statement and the first SCENARIO will be executed as the first step for each SCENARIO in a Feature file. That means 2 things:

• You can only have one BACKGROUND statement for a given set of SCENARIOS.
• The BACKGROUND must precede all SCENARIO statements for testing a given User Story, Feature, etc.

To illustrate the usage, I added another Scenario. In the first Scenario, the student requested a class schedule and had unfinished classes. The desired outcome in that situation is to show the class schedule.

In the second Scenario the student requests a class schedule and has NO unfinished classes. The desired outcome here is to offer a certificate of completion.

Using the Background statement, we express the Scenarios as follow:

BACKGROUND
GIVEN Student is logged into the website
AND Student has completed BASE

SCENARIO 1: Student requests schedule and has unfinished classes
GIVEN Student has unfinished classes
WHEN Student requests class schedule
THEN Student’s customized training plan is viewable

SCENARIO2: Student requests class schedule and has finished all required classes
GIVEN Student has no unfinished classes.
WHEN Student requests class schedule
THEN Student is offered a certificate of completion

Avoid repeating common set-up steps by using Background statements wherever possible. They make updating common preconditions much faster. They also are less error-prone and save time.

Select the Best Data Values for Your Given-When-Then Scenarios & Test Cases

Have you ever experienced the frustration of not knowing how many tests are enough to verify a User Story or a functional requirement? In our experience, having a thundering herd of Test Cases can be just as detrimental to the success of your newest release as having not enough.

In our instructor-led classes, we have been asked many times “How can we select the best data values for Test Cases or Scenarios”. The answer is “Test Data Engineering”.

The following video has a few tips on how to use this technique that applies concepts such as “equivalence classes”, “boundary values”, and “probable errors” to limit the amount of tests you need to write.

Given-When-Then Examples for Non-functional Requirements (NFRs)

Most of your Scenarios will test the functionality of the product or feature, but non-functional testing is as important as functional testing. If you want to ensure customer satisfaction do not neglect writing Scenarios that test Non-Functional Requirements (NFR) of the product as well.

As a refresher, NFRs express conditions such as how many, how often, how fast, how friendly, etc. Any of the four common types (Constraints, Performance, User Experience, or Volatility) should be tested. Testing Non-Functional Requirements can be extremely time- and resource-intensive. For that reason, many organizations have specialists whose primary job is performance testing, security testing, usability testing, etc.

However, if an NFR is important to the success of a product or feature, you should define User Acceptance Criteria or UAT Test Cases that will instill the confidence that the Non-functional Requirement has been met.

Here is an example to illustrate:

As golf tournament director, I can adjust a player’s net stroke play scores using their individual USGA handicaps to determine their net placement in the tournament.

User Story Decomp revealed the following NFR:

A player’s handicap must be a valid USGA handicap

There are definitively two Scenarios needed for this NFR. One where the player has a valid USGA handicap and another where they do not.

For example, if the player has proof of their USGA handicap, the Scenario reads:

Scenario: Golfer registers with a valid USGA handicap
GIVEN Golfer has signed-up for the tournament
AND Golfer registers on the day of tournament for play
WHEN Golf Pro requests proof of USGA handicap
AND Golfer shows an official USGA handicap card
THEN Golfer is assigned a tee time

And if the player has no official USGA handicap:

Scenario: Golfer registers without a valid USGA handicap
GIVEN Golfer has signed-up for the tournament
AND Golfer registers on the day of tournament for play
WHEN Golf Pro requests proof of USGA handicap
AND Golfer does not have an official USGA handicap card
THEN Golfer leaves in tears because he is not allowed to play

You could have more Scenarios for this NFR. For example: What if a player from Europe participates? Handicaps in Europe are regulated by the R&A (Royal and Ancient Golf Club, based in St. Andrews, Scotland). This may require another Scenario unless an R&A handicap is accepted by the USGA as “official” handicap.

Gherkin Scenario Outline Examples Extend the Given-When-Then Format

What happens if you want to test a Given-When-Then Scenario several times with different data? Do you have to create a Scenario for each data set? That would be a lot of wasted effort – definitely not LEAN!

This situation is extremely common in testing. Typically, a single test is insufficient to prove that the application reacts as we intended. We need to prove that the application reacts correctly under a variety of circumstances which are represented with different data values.

Rewriting Scenarios with many different data values quickly becomes tedious and repetitive. Scenario Outlines together with Examples reduce this effort considerably.

A Scenario Outline also uses the GWT syntax. However, it uses variables instead of constants to allow for the execution of a multitude of tests with a single Scenario statement. It avoids constant values like “Fred”, but instead refers to a “person”.

The Scenario Outline is followed by an Example Table that contains the various values assigned to each variable. Each row in the Example Table will be executed as a single Test Scenario.

To summarize Gherkin syntax,

• A SCENARIO has constants and NO variables.
• With a BACKGROUND you can minimize redundancies in SCENARIOS.
• A Scenario OUTLINE has variables that are filled using an EXAMPLE Table.
• Each row in the EXAMPLE Table will be executed as one SCENARIO.
• A SCENARIO outline can have an unlimited number of EXAMPLES.

To sum up

Gherkin Given-When-Then is a straightforward and simple language that allows non-technical people to describe clearly and concisely what they expect from a product or a feature.

It helps transform user requirements into executable business specifications thereby adding clarity to the entire software development process.

The Gherkin language is a perfect fit for User Acceptance Criteria and for describing User Acceptance Tests (UAT).

It will greatly help you improve communication (and documentation) with stakeholders by using a common language. 

What is your experience using Gherkin to define Acceptance Criteria and Scenarios for Acceptance Testing?

Please leave a comment below!