The Rules of Gherkin Syntax

Learning Objectives

By the end of this lesson you will be able to:

Identify the structural elements of a Gherkin file: Feature, Scenario, and steps
State the required order of Given/When/Then steps
Recognize common syntax mistakes before they cause confusion

The Skeleton of a Gherkin File

Every Gherkin file follows the same skeleton:

Feature: Discount code application

  Scenario: Valid code reduces the total
    Given a cart containing one item priced at $50
    When the user applies the discount code "SAVE10"
    Then the cart total reflects a 10% discount

Feature — the capability being described, one per file, usually a short noun phrase
Scenario — one concrete example of that feature's behavior; a Feature can (and usually does) contain multiple Scenarios
Steps — the Given/When/Then lines that make up the scenario's body

The Order Is Not Optional

Gherkin doesn't enforce step order at the parser level for every implementation, but the convention — and the readability contract — is strict: Given steps come first, then exactly one When, then Then steps. Breaking this order doesn't just look wrong; it actively confuses the reader about cause and effect.

# Wrong — Then before When makes no sense to a reader
Then the cart total reflects a 10% discount
When the user applies the discount code "SAVE10"
Given a cart containing one item priced at $50

One Feature, Many Scenarios

A single Feature file typically holds several Scenarios, each covering a different case of the same capability:

Feature: Discount code application

  Scenario: Valid code reduces the total
    Given a cart containing one item priced at $50
    When the user applies the discount code "SAVE10"
    Then the cart total reflects a 10% discount

  Scenario: Expired code is rejected
    Given a cart containing one item priced at $50
    When the user applies the expired discount code "OLD20"
    Then the system shows an "expired code" error

This is how Gherkin scales: not by cramming more logic into one scenario, but by adding more scenarios, each a clean example.

Indentation and Readability

Gherkin is whitespace-sensitive for readability, though most parsers are forgiving about exact indentation. Convention matters here even where the parser doesn't enforce it: indent Scenarios under Feature, and steps under Scenario, consistently. A scenario that's hard to visually scan is a scenario nobody will maintain correctly.

Pro Tip: If you find yourself needing two When steps in one scenario, that's usually a sign the scenario is doing two things at once. Split it — you'll learn exactly why in a later lesson.

Key Takeaways

A Gherkin file has a Feature, one or more Scenarios, and Given/When/Then steps inside each
The conventional step order is Given → When → Then, and violating it damages readability
One Feature commonly holds multiple Scenarios, each a distinct example
Consistent indentation isn't cosmetic — it's what keeps a growing scenario file scannable