Free Gherkin editor · no login

Gherkin Syntax: Learn It by Writing It

Gherkin is the plain-text format for describing how software should behave, one Given-When-Then example at a time. Below is an editor where you can write it right now. It suggests keywords as you type and flags syntax errors on the spot, so you learn the Gherkin syntax by using it. No login, no install, no IDE.

Free, stays freeRuns in your browserDownload as .feature

Try it: edit the example or start from scratch

Feature: Request annual leave
As an employee
I want to request annual leave
So that my manager can approve it before I book travel
Rule: Employees cannot request more days than their remaining balance
Scenario: Request within the remaining balance
Given Maria has 10 days of annual leave left
When she requests 3 days of leave
Then the request is sent to her manager
And her remaining balance still shows 10 days
Scenario: Request above the remaining balance
Given Maria has 2 days of annual leave left
When she requests 3 days of leave
Then the request is rejected
And she sees how many days she has left

Click anywhere in the text to edit it.

No errorsrequest-annual-leave.featureNothing is stored. Download before you close the tab.

Writing scenarios for a real feature? Speclr interviews your team first, so you write the right ones.

Start your 14-day trial

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.

request-annual-leave.feature
Feature: Request annual leave
As an employee
I want to request annual leave
So that my manager can approve it before I book travel
Rule: Employees cannot request more days than their remaining balance
Scenario: Request within the remaining balance
Given Maria has 10 days of annual leave left
When she requests 3 days of leave
Then the request is sent to her manager
And her remaining balance still shows 10 days
Scenario: Request above the remaining balance
Given Maria has 2 days of annual leave left
When she requests 3 days of leave
Then the request is rejected
And she sees how many days she has left

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

KeywordWhat it does
FeatureNames the capability the file describes. Must come first. Free-text description may follow.
RuleGroups the scenarios that illustrate one business rule.
BackgroundSteps that every scenario in the feature (or rule) shares. They run before each scenario.
Scenarioalias ExampleOne concrete example of the behavior.
Scenario Outlinealias Scenario TemplateOne scenario that is repeated with different data. Uses <placeholders>.
Examplesalias ScenariosThe data table that feeds a Scenario Outline.
GivenThe starting context.
WhenThe event or action.
ThenThe outcome you can observe.
AndButContinue the previous step type, so you do not repeat Given, When or Then.
*A bullet-style step. Rarely used.
@tagA 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.

Scenario Outline
Scenario Outline: Check the leave balance
Given Maria has <balance> days of annual leave left
When she requests <requested> days of leave
Then the request is <outcome>
Examples:
| balance | requested | outcome |
| 10 | 3 | accepted |
| 3 | 3 | accepted |
| 2 | 3 | rejected |

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.

Background:
Given Maria is logged in as an employee

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.

Tags, comments, docstrings and data tables

Tags start with @ and sit above the element they label. Tools use them to filter, for example to run only the scenarios tagged @smoke.

@leave @smoke
Scenario: Request within the remaining balance

A line that starts with # is a comment. Use comments sparingly. If a scenario needs a comment to be understood, rewrite the scenario.

A docstring passes a block of text to a step:

Then the manager receives this message:
"""
Maria requested 3 days of leave.
Please approve or decline.
"""

A data table passes structured data to a step:

Given the following leave balances:
| employee | days |
| Maria | 10 |
| Tom | 2 |

Mistakes to avoid in first scenarios

  1. 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 yellow
  2. Several When steps.

    One scenario, one action. Split the rest.

    The editor marks this red
  3. Vague outcomes.

    “Then it works” cannot be checked. Name the observable result.

  4. Scenarios that depend on each other.

    Each scenario must run on its own, so put shared context in a Given or a Background.

  5. 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

Don’t just write Gherkin. Do spec-driven development.

Once you know the keywords, the hard question remains: which scenarios should you write? Most teams write them alone, from a ticket, and find out in review, or after the coding agent has built it, that a stakeholder meant something else.

Spec-driven development turns that around. The spec comes first. The people who own the requirements agree on it, and it drives what gets built, by developers or by coding agents. Gherkin is how you write the result down. It is not how you find it.

Speclr guides your whole team from a vague product idea to a spec that developers and coding agents can build from.

With Speclr

  • It interviews you and asks the questions you forgot, so scenarios come out of a conversation and not out of a blank page.
  • It reviews the result from several perspectives, such as risk, QA, security and architecture.
  • It exports the finished scenarios to your repository and ticket system.
  • You keep control of every decision.
Start your 14-day trial

Runs in your browser. No terminal, no separate AI subscription.

FAQ

Questions about Gherkin syntax

Gherkin syntax is the set of keywords and rules used to write behavior as structured plain text. A file starts with Feature, contains Scenario blocks, and each scenario is a list of steps beginning with Given, When, Then, And or But.