Gherkin in a nutshell¶
Gherkin was designed for writing behavior specifications in a human-readable format for Behavior-Driven Development (BDD).
In Behavior-Driven Development (BDD), tests are written before the actual code. This is part of the test-first approach, where scenarios are written based on the expected behavior of the system before development begins.
So the first things we do is writing tests, in english language, with the gherkin syntax.
Note
If you are already familiar with gherkin, you may skip this chapter.
Starts with a simple Gherkin Scenario¶
Lets start by this simple example:
Feature: **feature description**
Scenario: **scenario description**
Given **context**
When **action**
Then **outcome**
Now what’s in the ** placeholder has to be replaced by something concrete
that have to be achieved.
It matches the definition of done.
Once the scenario has been written, the step definition has to be written for the scenario.
What we call steps, is keywords Given, When and Then.
The step definition is the function thas have been decorated by @given, @when, @then decorators.
In this chapter, we are not going to dive deeper on that, but, in real life, after writing a scenario in your repository, the first things to do is to run the tests and implement the missing steps definition.
Work in progress¶
While working on a new feature, I usually add a gherkin tag @wip, on the scenario.
It helps to stay focus on what you are working on.
Feature: **feature description**
@wip
Scenario: **scenario description**
Given **context**
When **action**
Then **outcome**
To run the tests marked with wip use the command pytest with the option -m wip.
See chapter Gherkin tag as pytest tag for more.
Adding another scenario¶
When the first scenario works, you may write a new scenario and mark it as @wip.
Feature: **feature description**
Scenario: **scenario description**
Given **context**
When **action**
Then **outcome**
@wip
Scenario: **new scenario description**
Given **context**
When **action**
Then **outcome**
Use background to avoid repetition¶
You may have multiple scenario in one feature file, usually, the given context may be the same, and, if it is the case, the scenario can be refactor using a Background keyword.
Feature: **feature description**
Background:
Given **context**
Scenario: **scenario description**
When **action**
Then **outcome**
@wip
Scenario: **new scenario description**
When **action**
Then **outcome**
In that case, the 2 scenario starts with the same given step.
Adding more steps¶
Feature: **feature description**
Scenario: **scenario description**
Given **context**
And **context 2**
When **action**
And **action 2**
Then **outcome**
And **outcome 2**
But **outcome 3**
You can add multiple step and avoid repetition of the Given When or Then by using a conjunction, which is And or But. They are just here for clarity. the step definition is still using the same @given, @when, @then decorators.
Use scenario outline to avoid repetition¶
Using a When happen after a Then, or even aGiven is valid, but, this is not recommended.
Feature: **bad feature description**
Scenario: **scenario that is badly designed**
Given **context**
When **action** value11
Then **outcome** value12
When **action** value21
Then **outcome** value22
should be writen
Feature: **bad feature description**
Scenario Outline: **scenario rewritten**
Given **context**
When **action** <param1>
Then **outcome** <param2>
Examples:
| param1 | param2 |
| value11 | value12 |
| value21 | value22 |
Using the gherkin chevron-enclosed placeholders (
Use data table to load multiple data.¶
Feature: **feature description**
Scenario: **scenario description**
Given **big contextcontext**:
| param1 | param2 |
| value11 | value12 |
| value21 | value22 |
When **action**
Then **outcome**
it allows to have a step definition having a complex python type.
Note that it works also for the When and the Then keywords.
Now that we know gherkin, its time to dive into the next chapter and define how we define the step definition using the pattern matcher.