What is Gherkin?
Gherkin is a structured language designed to make user stories easier to understand — for both technical and non-technical people. At the same time, its syntax is precise enough to describe usage examples and clearly illustrate business rules.
Why use Gherkin? Is it required?
Using Gherkin isn’t required to write user stories. However, it’s becoming increasingly common in the industry — and for good reason. When written in a structured format, user stories improve communication between teams and stakeholders and can also serve as the foundation for executable specifications and automated testing.
Gherkin and executable specifications (automation)
User stories can be organized into separate files, each containing a concise set of scenarios. This makes them more specialized and self-contained. These files — called features — are readable by the application and, because they include details like inputs, outputs, constraints, examples, and acceptance criteria, they make excellent assets for building automated tests.
Gherkin Keywords
Gherkin uses specific keywords to structure stories:
- Feature
- Background
- Scenario
- Scenario Outline
- Examples
- Given
- When
- Then
- And
- But
*(asterisk)
Explaining Each Keyword
Feature
Defines the name of the feature being described. It groups related scenarios around a specific business context and usually includes a short description of the feature’s goal.
Background
Lets you define a set of steps that apply to every scenario in the file. This avoids duplication and keeps scenarios clean and readable. It also helps with test maintenance if the stories are tied to automation.
Scenario
Represents a specific, concrete example of how the system should behave. Each scenario includes the full flow: inputs, actions, and expected outcomes.
Scenario Outline
Useful when you have several similar scenarios where only the data changes. Instead of repeating the same structure, you use a template — the Scenario Outline — with different sets of values. This reduces repetition and improves clarity.
Examples
Examples accompany a Scenario Outline and provide the input/output values. For each row in the example table, the same scenario is executed with different data — enabling broader and more precise testing.
Given / When / Then
These keywords define the scenario’s structure and help keep logic clear. They’re not mandatory, but they represent the three essential parts of any scenario:
- Given: the initial context (e.g. existing data, system state)
- When: the user action or event
- Then: the expected result
And / But
Used to add steps or exceptions to a scenario:
- And: adds a new step
- But: introduces a variation or exception
❌ Example of What Not to Do
Scenario: validate whether I can enter the cinema based on my age
Given I am 13 years old
And I want to watch a movie rated 14+
But I can watch it if accompanied by a guardian
When I try to enter the cinema
Then I should be denied entry due to my age
But if I’m accompanied by a guardian
Then I should be allowed inThis is a great example of what not to do. The story lacks clarity, includes unnecessary steps, and tries to validate multiple cases at once. Couldn’t we split this into more than one scenario? Or maybe use a Scenario Outline?
To decide whether a Scenario Outline is appropriate, ask yourself:
Would it be better to separate this into multiple scenarios?
Or would a Scenario Outline with different examples be more effective?
In my opinion, the choice is somewhat personal — but we should always prioritize clarity when writing user stories.
✅ Example of What to Do
Scenario: Minor tries to enter restricted movie alone
Given I am 13 years old
And the movie is rated 14+
When I try to enter the cinema without a guardian
Then my entry should be denied
Scenario: Minor tries to enter restricted movie with guardian
Given I am 13 years old
And the movie is rated 14+
And I’m accompanied by a guardian
When I try to enter the cinema
Then I should be allowed in
Scenario: Can you think of a third one? Leave a comment.Using a Scenario Outline for “the same” case:
Scenario Outline: Validate cinema entry based on age and accompaniment
Given I am <age> years old
And the movie is rated <rating>
And I am <accompanied>
When I try to enter the cinema
Then entry should be <result>
Examples:
| age | rating | condition | result |
| 13 | 14 | unaccompanied | denied |
| 13 | 14 | accompanied | allowed |
| 16 | 14 | unaccompanied | allowed |You can learn more about user stories by visiting this post (clique here).
Or by accessing the User Stories category.
What about the * (Asterisk)?
Sometimes it’s hard to structure scenarios using traditional keywords (Given, When, Then, etc.). In these cases, using the asterisk * as a generic step marker can improve readability and make writing easier.
In many situations, poorly written scenarios become much clearer when rewritten using *. The important thing is to always reflect on the structure — it’s never a waste of time, since clarity is the goal.
Let’s revisit our example and rewrite it using *:
Scenario: validate whether I can enter the cinema based on my age
* I am 13 years old
* the movie I want to watch is rated 14+
* I try to enter the cinema without a guardian
* my entry is denied due to my age
Scenario: Minor tries to enter restricted movie with guardian
* I am 13 years old
* the movie I want to watch is rated 14+
* I am accompanied by a guardian
* I try to enter the cinema
* my entry is allowed
Scenario: Can you think of a third one? Leave a comment.The structure is the same, but this version is cleaner and more direct. Using * can simplify writing, especially when the traditional prefixes don’t add much.
⚠️ Caution When Using *
While using * gives more flexibility, it should be used with care. Without a defined structure, it’s easier to add irrelevant or poorly phrased steps.
Even without the prefixes, a clear scenario flow — context → action → expected outcome — must still be followed.
Compare:
✅ “I am 13 years old” — clear and relevant; defines a key condition
❌ “I want to watch a movie” — vague; just expresses a desire
✅ “I want to watch a movie rated 14+” — adds a useful constraint
Using * can be a great way to simplify writing, but never at the expense of clarity, logic, or value. Keep the focus on communication and usefulness — whether or not you use the formal Gherkin structure.
Final Thoughts
Gherkin is more than just a way to write user stories — it’s a bridge between people, teams, and technology. When used well, it turns vague requirements into clear, collaborative, and even automatable scenarios.
Clarity matters more than formality.
The ultimate goal is the same: to improve communication, align expectations, and make sure everyone’s on the same page. Taking the time to structure well-written stories isn’t optional — it’s essential for building better products.
Enjoyed the content? Drop your questions, suggestions, or feedback in the comments! Constructive criticism, praise, and new ideas are always welcome.