Transcripted Summary
In this chapter we'll be focusing on Gherkin.
Gherkin is a special syntax that is used within BDD to document examples.
Gherkin uses a set of special keywords to give structure and meaning to executable specifications.
The files that are used to store Gherkin are referred to as feature files because each file is usually used to document the behavior for one feature
Each group of instructions that relate to the actions and behavior of an individual scenario of a feature is actually referred to as an example or a scenario
Some of the core keywords of Gherkin are: Feature, Scenario, Example, Given, When, and Then. We'll dive into what each keyword means, when to use them, and the best practices surrounding them.
This is the standard layout of an Example written in Gherkin — each line starts with a keyword followed by some descriptive text.
I've outlined here what each of the keywords is meant to achieve.
We start with the
Featurekeyword whose descriptive text outlines the feature, it's expected behavior, and how it relates to a business requirement.Then we have a
Scenariokeyword whose descriptive text outlines the specific business situation related to the feature.Following that we have
Given,When, andThen— the cornerstone of Gherkin scenarios.
Each line in an example that begins with Given, When, or Then is called a Step.
These are responsible for explaining the state of a system or linking an action and the expected behavior. We’ll learn more about these keywords in a few slides.
Here is a scenario outlining the withdrawal feature of an ATM machine.
As we can see, Gherkin is written in English like statements making it easy for anyone to understand.
Let's go through this one together.
# This explains the feature and maps it back to an important business requirement.
Feature: Withdraw money. A customer should be able to withdraw cash from the machine at any given time.
# This is a title for the specific scenario of the feature. This outlines that the user is trying to withdraw money from their account when they have available money.
Scenario: Withdraw cash with money available
# This outlines a precondition for the system.
Given I have available funds in my account.
# This is the action to be performed.
When I select the withdraw option
# This is the expected behavior of the system.
Then I should get cash.
Now, this is an oversimplified scenario for our withdraw money Feature. I'm sure we can think of many more preconditions that need to be met, like money needs to be available in the ATM machine or the user has entered their pin correctly.
But this is just an example of how Gherkin can be mapped to this real-world system and more importantly, this scenario should be linked directly to a business requirement of the system being built.
Try It On Your Own
I want you to go ahead and try writing the Gherkin steps for the following scenario: Withdraw cash with no money available.
# Gherkin Syntax
Now, that we see at the high level of what we can create with Gherkin, let's define some of the other keywords you can use and when to use them.
Here are a few you're already familiar with.
Given— used to outline some preconditions that are necessary for this scenario to be executed by a user. For example, Given I am logged in as an administrator.When— used to describe the action to be performed. For example, When I create a user.Then— used to describe the outcome from the action. For example, Then the user is created.AndorBut— these can be used to duplicate any previous keyword. For example, the scenarios in the image below are identical and are both valid.
You can choose which approach you want to take, but personally using And, and But can make a scenario easier to read.
Feature— this must be the first word in a Gherkin document or a feature file. The purpose of this keyword is to provide a high-level description of a featureScenarioorExample— this is a summary of the specific scenario of the feature of being describedBackground— this is used when you have a set of steps that you want to repeat for multiple scenarios
In the image below, on the right, we see a snippet from a feature file; let's break it down.
We have one Background followed by two Scenarios.
What this means is before the first step of each scenario is executed, the steps that belong to the background will be executed. So, we can see both these scenarios rely on a user being logged in as an administrator.
Scenario Outline— this is useful when you want to run the same scenario with different values. It is used in conjunction with theExampleskeywordExamples— also referred to as data tables, are used to outline the values to be used within aScenario Outline.Examplesare represented in a table format
Let's dive into an example.
On the right, we have an example using a Scenario Outline and Examples; let's break it down.
We have one Scenario Outline and one Examples section with three rows.
In our Scenario Outline, we see some angled brackets (<variable>).
These brackets are on variables that will be replaced by the values in the data table.
The first row of the data table is the column headings, and these map to the variables that will be replaced in the
Scenario OutlineThe remaining rows contain the values to be used — each row represents a different scenario.
Below we have replaced the variable names in the scenario outline to translate what the first data row of the example would give us.
The combination of this Scenario Outline and data table would produce 2 scenarios with identical steps, just different values.
# Gherkin Best Practices
Let's move on to some Gherkin best practices.
Create modular, reusable steps, and actually reuse them.
Instead of creating a step to withdraw $100, create a step to withdraw any amount of money. One of the most common mistakes people make is to create Gherkin steps that are too detailed and not reusable.
Create behavior-driven steps, not procedural.
Write steps as if being written by a user. Avoid steps referring to specific elements or selectors. This is a part of the process of Gherkin steps being developed by the 3 Amigos. The step generated must be understood clearly by the stakeholders and not specific to some part of the code or an element on the interface.
Each scenario should represent one behavior.
When creating steps for a Scenario, try to limit the scope of it to 1 behavior for that feature.
Utilized Backgrounds and Scenario Outlines as much as possible.
You can utilize these keywords as they can help to make your feature files more concise.
Avoid excessive use of And and But.
If you find yourself using 3 or more And’s or But’s consecutively, chances are you aren't following the previous steps. You may be trying to create steps that are not reusable or steps that are too tightly coupled with the UI.
And finally, try not to use punctuation, specifically periods and commas, within step phrases.
These can become a pain later on when trying to debug why your steps aren't working.
# Example of Best Practices for Gherkin Syntax
Let's compare these 2 feature files that I got from automationpanda.com and discuss why the one on the right is a better alternative for the one on the left.
In the feature file on the left, the first 2 steps, are purely set up.
Given the user opens up a web browserAnd the user navigates the google.com
All they do is go to Google and they are strongly procedural.
Since they don't focus on the desired behavior, they can be combined into 1 step such as, Given a web browser is at the Google home page.
After the Given steps, there are 2 When, Then pairs — this is tactically incorrect.
Given, When, and Then steps must appear in order.
A Given may not follow a When or Then; and a When may not follow a Then. The reason is because a single When, Then pair knows an individual behavior. This makes it clear that the scenario on the left is testing 2 behaviors, which according to our best practices we should not be doing.
That's why it's best to split these out into 2 separate scenarios as we have done on the right.
And that covers it. That's the end of our brief overview of Gherkin, its syntax and best practices.
