SpecFlow - Gherkin Keywords

The main Gherkin keywords are −

Feature
Scenario
Rule(till Gherkin 6)
Example or Scenario
Background
Scenario Outline
Examples
| for Data table
""" for Document Strings
@ for Tags
# for Comments
Given
When
Then
But
And

Gherkin uses localization for multiple languages and each of the above keywords has its equivalent terms in respective languages.

Let us explore some of the important Gherkin keywords −

Feature

A Feature is added to have an overall description of the features of the applications and to club connected scenarios. This is the most important keyword in a Gherkin document.

A Feature is followed by a colon: symbol and then a small description on the feature. We can add multiple lines for more description. These are not considered by SpecFlow at execution but are added in the html reports.

Once the description of a Feature is completed, we should begin a new line with keywords Background, Example, and so on. We can add tags above Feature to club similar features, irrespective of the structure of file or directory.

Scenario

Scenario is a complete instance that describes a business logic. It has multiple steps. It is often considered a synonym of keyword Example. A Scenario does not have a fixed number of steps. But it is recommended to have 3 to 5 steps per Scenario.

If there are too many steps, it may lose its value to be used as specification and documentation. A Scenario is like a test in a development lifecycle. Also, it can be divided into a precondition, test step and verification.

Given

Given are steps used for describing the pre-existing condition of the system. It typically deals with the events that have occurred in the past. As a Given step is executed, it shall set the objects, test data in the database and put the system in a proper state.

Thus, the Given step helps to define the system in a known condition prior to the interaction of the user with the system. We can have multiple Given steps. Two or more Given steps can be used with And keyword. In short, it is used to have the preconditions defined.

When

When is a step used for describing an action or an incident. This can either be an interaction of the person with the system or an incident caused by another system. It is a good practise to have a single When step in a Scenario.

If we are forced to have multiple When steps, we should ideally break the Scenario into smaller ones.

Then

Then is a step used for describing an expected result. The corresponding step definition of a Then step should have an assertion to verify actual result against the expected result.

Thus, it basically deals with the output obtained from the tests (message, report, and so on) and not on the internal characteristics of the system, for instance a database record. In other words, it is used for an outcome that is noticeable from the end user perspective.

But, And

If we have repeated Given, When and Then steps, then we can make the Scenarios more organized by replacing the consecutive Given, When, Then steps with And, But steps.

The above example shows the usage of And and But.

The * symbol

The * symbol is used in place of another step keyword. This can be used for steps that represent a list of items. It is more like a bullet point. For the below example, two And steps have appeared one after the other.

The consecutive And steps should be represented like this −

Background

Sometimes, we may require repeating the same steps for all Scenarios within the Feature file. We may shift these steps to the backdrop by clubbing them under the Background segment.

It helps to add context to a scenario. It can have more than one Given step. Thus, it shall execute prior to execution of each Scenario, but post any Before hooks.

A Background is kept prior to the first Example or Scenario, at the similar indentation level. In short, Background is used for declaring the common steps to all the tests.

In the above example, having two Scenarios, the Background steps shall run once before execution of each of these scenarios.

Scenario Outline

Scenario Outline is used to replicate the same Scenario with a different data set. Writing the same tests with different values is cumbersome and time taking. For instance,

We can club the above two scenarios with the Scenario Outline.

Thus, we see that a Scenario Outline should be accompanied with keyword Examples. A Scenario Outline is executed once for each of the rows appearing below the Examples segment.

Also, we have seen that the Given step has the <> delimiter. It points to the header of the Examples table. SpecFlow shall put the values within this table prior to the task of matching a step with a Step Definition.

Data Table

Data Table is used to send a group of values in the form of a list to the Step Definition file. It is useful to deal with large data sets. SpecFlow has a rich API for table manipulation in the Step Definition File.

SpecFlow Assist Helpers packages are used to work on tables. Also, we have to add namespace TechTalk.SpecFlow.Assist to our code.