Gherkin is a language, which is used to write Features, Scenarios, and Steps. The purpose of Gherkin is to help us write concrete requirements.

To understand what we mean by concrete requirements, consider the following example −

Customers should be prevented from entering invalid credit card details.

Versus

If a customer enters a credit card number that is not exactly 16 digits long, when they try to submit the form, it should be redisplayed with an error message advising them of the correct number of digits.

The latter has no ambiguity and avoids errors and is much more testable.

Gherkin is designed to create requirements that are more concrete. In Gherkin, the above example looks like −

Feature

Feedback when entering invalid credit card details Feature Definition

In user testing, we have seen many people who make mistakes Documentation

Background True for all Scenarios Below

Given I have chosen an item to buy,

And I am about to enter my credit card number

Scenario − Credit card number too shortScenario Definition

When I enter a card number that is less than 16 digits long

And all the other details are correct

And I submit the formSteps

Then the form should be redisplayed

And I should see a message advising me of the correct number of digits

Gherkin Format and Syntax

Gherkin files are plain text Files and have the extension .feature. Each line that is not blank has to start with a Gherkin keyword, followed by any text you like. The keywords are −

• Feature

• Scenario

• Given, When, Then, And, But (Steps)

• Background

• Scenario Outline

• Examples

• “”” (Doc Strings)

• | (Data Tables)

• @ (Tags)

• # (Comments)

• *

Feature

The Feature keyword is used to describe a software feature, and to group the related scenarios. A Feature has three basic elements −

• The keyword – Feature.

• The name of the feature, provided on the same line as the Feature keyword.

• An optional (but highly recommended) description that can span multiple lines i.e. all the text between the line containing the keyword Feature, and a line that starts with Scenario, Background, or Scenario Outline.

In addition to a name and a description, Features contain a list of scenarios or scenario outlines, and an optional background.

It is conventional to name a .feature file by taking the name of the Feature, converting it to lowercase and replacing the spaces with underlines. For example,

feedback_when_entering_invalid_credit_card_details.feature

In order to identify Features in your system, you can use what is known as a “feature injection template”.

In order to <meet some goal> as a <type of user> I want <a feature>

Descriptions

Some parts of Gherkin documents do not have to start with a keyword.

In the lines following a Feature, scenario, scenario outline or examples, you can write anything you like, as long as no line starts with a keyword. This is the way to include Descriptions.

Scenario

To express the behavior of your system, you attach one or more scenarios with each Feature. It is typical to see 5 to 20 scenarios per Feature to completely specify all the behaviors around that Feature.

Scenarios follows the following pattern −

• Describe an initial context

• Describe an event

• Describe an expected outcome

We start with a context, describe an action, and check the outcome. This is done with steps. Gherkin provides three keywords to describe each of the contexts, actions, and outcomes as steps.

• Given − Establish context

• When − Perform action

• Then − Check outcome

These keywords provide readability of the scenario.

Example

Scenario − Withdraw money from account.

• Given I have $100 in my account.

• When I request $20.

• Then $20 should be dispensed.

If there are multiple Given or When steps underneath each other, you can use And or But. They allow you to specify scenarios in detail.

Example

Scenario − Attempt withdrawal using stolen card.

• Given I have $100 in my account.

• But my card is invalid.

• When I request $50.

• Then my card should not be returned.

• And I should be told to contact the bank.

While creating scenarios, remember ‘each scenario must make sense and be able to be executed independently of any other scenario’’. This means −

• You cannot have the success condition of one scenario depend on the fact that some other scenario was executed before it.

• Each scenario creates its particular context, executes one thing, and tests the result.

Such scenarios provide the following benefits −

• Tests will be simpler and easier to understand.

• You can run just a subset of your scenarios and you do not have to worry about the breaking of your test set.

• Depending on your system, you might be able to run the tests in parallel, reducing the amount of time taken to execute all of your tests.

Scenario Outline

If you have to write scenarios with several inputs or outputs, you might end up creating several scenarios that only differ by their values. The solution is to use scenario outline. To write a scenario outline,

• Variables in the scenario outline steps are marked up with < and >.

• The various values for the variables are given as examples in a table.

Example

Suppose you are writing a Feature for adding two numbers on a calculator.

Feature − Add.

Scenario Outline: Add two numbers.
Given the input "<input>"
When the calculator is run
Then the output should be <output>"
Examples
| input    | output |
| 2+2      | 4      | 
| 98+1     | 99     |
| 255+390  | 645    |

A scenario outline section is always followed by one or more sections of examples, which are a container for a table. The table must have a header row corresponding to the variables in the scenario outline steps. Each of the rows below will create a new scenario, filling in the variable values