Once you know the syntax, keep using it. Write your own scenarios, download them as a .feature file and hand them over. Product owners, business analysts, requirements engineers and testers use it this way without opening a development environment.
What a Gherkin feature file looks like
A feature file describes one capability of a product. It has a name, an optional description, and a set of concrete examples called scenarios. Each scenario is written as a short sequence of steps.
Read it from the top. Feature names the subject. The three lines below it are free text that explain why the feature exists. Rule states one business rule, and the two scenarios underneath are examples of that rule. Every step starts with a keyword, and the rest of the line is plain language that anyone on the team can read.
The file extension is .feature. Indentation is not part of the grammar, but two spaces per level is the common convention.
All Gherkin keywords at a glance
| Keyword | What it does |
|---|---|
Feature | Names the capability the file describes. Must come first. Free-text description may follow. |
Rule | Groups the scenarios that illustrate one business rule. |
Background | Steps that every scenario in the feature (or rule) shares. They run before each scenario. |
Scenarioalias Example | One concrete example of the behavior. |
Scenario Outlinealias Scenario Template | One scenario that is repeated with different data. Uses <placeholders>. |
Examplesalias Scenarios | The data table that feeds a Scenario Outline. |
Given | The starting context. |
When | The event or action. |
Then | The outcome you can observe. |
AndBut | Continue the previous step type, so you do not repeat Given, When or Then. |
* | A bullet-style step. Rarely used. |
@tag | A label for filtering and grouping, placed above a Feature, Rule, Scenario or Examples. |
# | A comment line. |
""" | A docstring: a block of multi-line text passed to a step. |
| | Cell separator in a data table. |
Gherkin itself exists in many human languages, selected by a # language: line at the top of the file. This editor supports the English keywords only for now.
Given, When, Then: what goes where
Given
A state, not an action
Maria has 10 days of annual leave left
When
The one thing that happens
she requests 3 days of leave
Then
What you can observe afterwards
the request is sent to her manager
Given sets up the situation. It describes a state, not an action: “Maria has 10 days of annual leave left”.
When is the one thing that happens: “she requests 3 days of leave”. If you find two When steps in a scenario, you are usually looking at two scenarios.
Then states what you can observe afterwards: “the request is sent to her manager”. Describe the outcome as a user or another system would see it, not how the code gets there.
And and But carry on the previous keyword. “Then the request is rejected, And she sees how many days she has left” reads better than repeating Then.
Scenario Outline and Examples: same steps, different data
When several scenarios differ only in their values, write the steps once and put the values in a table. Placeholders in angle brackets are replaced with each row.
This runs as three scenarios. Keep the table small. If it needs many columns, the outline is probably doing too much.
Background and Rule: remove repetition, add structure
Background holds steps that every scenario in the same feature needs.
Use it for context that is true everywhere. Do not hide steps there that a reader needs to understand a single scenario.
Rule groups scenarios under the business rule they illustrate, as in the first example. It keeps long feature files readable and makes it clear which rule each example belongs to.
Mistakes to avoid in first scenarios
Steps that describe clicks.
“When I click the blue Submit button” breaks the first time the design changes. Write “When she requests 3 days of leave”.
The editor marks this yellowSeveral When steps.
One scenario, one action. Split the rest.
The editor marks this redVague outcomes.
“Then it works” cannot be checked. Name the observable result.
Scenarios that depend on each other.
Each scenario must run on its own, so put shared context in a Given or a Background.
Giant example tables.
If nobody reads the table, nobody reviews the behavior.
Syntax is the easy part. Knowing which examples to write is harder, and Speclr helps your team find them.
See how it works