Gherkin is a domain-specific language used to describe software behavior in clear, structured text. It plays a key role in Behavior Driven Development (BDD), improving communication between stakeholders such as developers, testers, and product owners through concrete examples.
The goal of Gherkin is to translate requirements into testable scenarios. Instead of vague descriptions or technical user stories, Gherkin focuses on describing behavior through examples that can be automatically tested with tools like Cucumber.
By using Gherkin, misunderstandings in specifications are reduced. Since the syntax is easy to understand for both technical and non-technical stakeholders, it helps improve collaboration and software quality throughout the development process.
A Gherkin file describes one or more scenarios within a feature. Each file starts with the keyword Feature, followed by a short description. Below that, scenarios are written that outline the desired behavior based on input and expected output.
Gherkin files typically have the .feature extension and can be interpreted by tools such as Cucumber, SpecFlow, or Behave. These tools link each scenario to automated test code.
Example structure:
Feature: Logging into the webshop
Scenario: Login with valid credentials
Given the user is on the login page
When the user enters a valid email and password
Then the user is redirected to the dashboardThe Gherkin syntax is simple but strict. Each line starts with a keyword, followed by descriptive text. The keywords organize the scenario into logical steps:
Feature: describes the functionality
Scenario: describes a specific example
Given: describes the starting situation
When: describes the action
Then: describes the expected outcome
And / But: optional, used to extend the above steps
This structure ensures that each scenario is easy to follow and directly links to the underlying software logic.
Every Gherkin file starts with the keyword Feature. It describes the behavior of a specific functionality and provides context for the scenarios underneath.
Example:
Feature: Password reset
In order to regain access to my account
As a user who forgot their password
I want to request a new passwordScenario is used to describe a specific use case where the user interacts with the system. Scenario Outline is used when you want to test the same structure with multiple sets of input data.
Example:
Scenario Outline: Logging in with different users
Given the user is on the login page
When the user logs in with "<username>" and "<password>"
Then "<result>" is displayed
Examples:
| username | password | result |
| jan@example.nl | welcome123| Welcome Jan! |
| wrong@example.nl| wrongpass | Invalid login |These are the core building blocks of every scenario:
Given: the starting condition or context
When: the action being performed
Then: the expected outcome or result
They are written in plain language so everyone on the team can easily understand them.
Example:
Given the user is logged in
When they click on 'Log out'
Then they are redirected to the login pageUse And or But to add extra steps that belong to a Given, When, or Then.
Example:
Given the shopping cart contains a product
And the user is logged in
When they click on 'Checkout'
Then the payment summary appearsBackground is used to define steps that apply to every scenario in a feature. This helps reduce repetition and keeps scenarios clean and readable.
Example:
Background:
Given the user is on the homepage
And the shopping cart is emptyIn an agile workflow, teams often start with a user story like:
“As a user, I want to reset my password so that I can log back in.”
That story gets translated into one or more Gherkin scenarios.
By thinking in concrete steps, it becomes clear how the feature should behave and which tests are needed.
A good Gherkin scenario:
is clear and concrete
uses real examples
has a logical structure
focuses on behavior, not technical implementation
Common mistakes to avoid:
Scenarios that are too long
Vague wording like “something happens”
Incomplete or overlapping steps
Gherkin is closely tied to test automation. Tools like Cucumber and Behave connect the written scenarios to code using step definitions, allowing automated execution of the tests.
Example:
Scenario: Logging in with valid credentials
Given the user is on the login page
When they enter their email and password
Then they are redirected to the dashboardCan be linked to test code written in Python, Java, or other languages to verify that this behavior works as expected.
Extended capabilities of Gherkin
In addition to the basic structure using Feature, Scenario, and Given-When-Then, Gherkin offers extra features that make scenarios more flexible and powerful. These advanced options are especially useful when working with reusable scenarios or structured input. As a result, test automation becomes not only more accurate but also easier to scale.
Sometimes, you need to pass additional data into a scenario. Gherkin supports this using Doc Strings and Data Tables.
A Doc String is used when you want to include a block of text or JSON inside a step.
Example:
Given the user fills in the following form:
"""
name: John
email: john@example.com
comment: I would like more information
"""A Data Table allows you to pass structured input, such as multiple fields or options.
Example:
Given the following products are added to the cart:
| product | price |
| Laptop | 999 |
| Mouse | 25 |Data Tables are ideal for testing multiple combinations or input sets.
A Scenario Outline is useful when you want to reuse the same step sequence with different input values. This avoids duplicating scenarios.
Example:
Scenario Outline: Applying discount code
Given the user enters "<code>"
When they click 'Apply'
Then they see "<message>"
Examples:
| code | message |
| WELCOME| 10% discount applied |
| INVALID| Code is not valid |Under the Examples section, you provide the data that will be substituted into the outline. This keeps tests clear and easy to maintain.
Gherkin supports multiple natural languages. This allows teams worldwide to write scenarios in their native language, such as Dutch, French, German, Spanish, or Turkish.
Example in Dutch:
Feature: Aanmelden # Feature: Sign up
Scenario: Succesvol aanmelden # Scenario: Successful registration
Gegeven een geregistreerde gebruiker # Given a registered user
Als de gebruiker zich aanmeldt met correcte gegevens # When the user logs in with valid credentials
Dan wordt hij doorgestuurd naar zijn profielpagina # Then they are redirected to their profile pageAdvantages:
More accessible for non-English teams
Increases domain experts’ involvement
Disadvantages:
Harder for international collaboration
Step definitions need to be maintained per language
Gherkin is widely used in software development, especially in agile teams that follow Behavior Driven Development (BDD). It helps align specifications between developers, testers, and business stakeholders. By writing concrete examples in natural language, communication improves and errors are prevented early in the development process.
Gherkin is not limited to a specific type of project or technology. Below are some of its common applications.
In agile workflows, collaboration and fast feedback are key. Gherkin supports this by complementing user stories with clear, testable scenarios. During refinement or sprint planning sessions, teams can work together to create these scenarios. This ensures that expectations are aligned before development begins.
For testers, these scenarios are directly executable through automation. For developers, they provide clear targets. For business stakeholders, they act as verifiable acceptance criteria.
Gherkin is commonly used in the following situations:
Web applications: for example, to test login flows, shopping carts, or search functionalities.
API testing: describing request-response behaviors in scenarios.
Mobile apps: testing user interactions like swiping or push notifications.
Thanks to its natural language structure, Gherkin is suitable for a wide range of domains; from e-commerce to financial software.
Gherkin offers a simple yet powerful way to describe software behavior. By using natural language, requirements become concrete, understandable, and directly testable. Especially within Agile and Behavior Driven Development (BDD), Gherkin improves communication between all parties involved.
With its clear structure, using Feature, Scenario, Given-When-Then, and additional options like Background, Scenario Outline, and Data Tables, nearly any desired behavior can be accurately described and tested. This reduces the risk of misunderstandings, improves software quality, and makes test automation more accessible.
For teams aiming for clear specifications and reliable software quality, Gherkin is a valuable tool in the development process.
Gherkin is used to capture functional specifications of software in a clear and testable way. By describing application behavior in natural language, both technical and non-technical team members can easily understand and validate the specifications. Gherkin also forms the basis for automated testing within Behavior Driven Development (BDD), where tools like Cucumber can directly execute the scenarios.
In agile environments, Gherkin is often used to complement user stories. During refinement sessions or sprint planning, the team collaboratively translates acceptance criteria into Gherkin scenarios. This helps prevent misunderstandings, improves collaboration between business and development, and enables automated testing to verify that the desired functionality has been correctly implemented.
