Gherkin Syntax
Gherkin is a plain-text language for describing software behavior. Feature files use a structured Given-When-Then format that both humans and BDD tools can execute.
//
Search across all documentation pages
Gherkin is a plain-text language for describing software behavior. Feature files use a structured Given-When-Then format that both humans and BDD tools can execute.
Feature: Invoice creation
As a billing clerk
I want to create invoices
So that customers receive accurate bills
Scenario: Valid invoice
Given an authenticated billing clerk
When they create an invoice for 100.00 USD
Then the invoice status is "draft"
And the invoice id is not emptyWhen to reach for this:
Feature: User registration
Users must register with a valid email before accessing the system.
Background:
Given the registration API is available
Scenario: Successful registration
Given no user exists with email "ada@example.com"
When a registration request is sent with:
| email | ada@example.com |
| password | SecurePass123 |
Then the response status is 201
And a confirmation email is queued
Scenario Outline: Invalid email rejected
Given no existing user conflicts
When a registration request is sent with email "<email>"
Then the response status is 422
Examples:
| email |
| not-an-email |
| @missing.com |
| empty |What this demonstrates:
Feature describes the capability with user story formatBackground runs before every scenario in the fileScenario is a single test case with Given-When-Then stepsScenario Outline + Examples parametrizes scenarios| Keyword | Purpose |
|---|---|
| Feature | Groups related scenarios |
| Background | Shared setup for all scenarios |
| Scenario | Single behavior example |
| Scenario Outline | Parametrized scenario |
| Given | Preconditions (arrange) |
| When | Action (act) |
| Then | Expected outcome (assert) |
| And / But | Continuation of previous step type |
| Examples | Data table for Scenario Outline |
When the user submits:
| field | value |
| name | Ada |
| amount | 100 |# language: fr header). Fix: one language per project.| Alternative | Use When | Don't Use When |
|---|---|---|
| pytest docstrings | Developer-only specs | Stakeholder-readable specs needed |
| OpenAPI examples | API contract docs | User workflow behavior |
| Markdown test plans | Pre-automation exploration | Executable tests needed |
No, but the Feature description should explain who benefits and why.
5-15 is manageable. Split large features into multiple files.
@smoke, @wip labels for filtering: pytest --tags smoke.
Yes with doc strings (""") for multiline step arguments.
Given = state, When = action, Then = assertion. And/But continue the previous type.
Then the response status is 403 or Then registration fails with "email taken".
Background for shared setup across all scenarios. Scenario-specific Given for unique preconditions.
Not recommended. Gherkin is for acceptance-level behavior. Use pytest for units.
Gherkin 6+ groups scenarios under business rules within a Feature.
Use relative terms in steps ("today", "next Monday") resolved in step definitions.
Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.
Reviewed by Chris St. John·Last updated Jul 19, 2026