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.
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 −
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 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 −
Given, When, Then, And, But (Steps)
""" (Doc Strings)
| (Data Tables)
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,
In order to identify Features in your system, you can use what is known as a “feature injection template”.
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.
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.
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.
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.
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.
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