Gherkin: Given-When-Then Syntax | Sean Dinwiddie's Webmastery

Updated October 4, 2026· Development

Gherkin is Cucumber’s plain-language format for Given-When-Then scenarios, the way behavior-driven development (BDD) writes down how software should behave; Given, When and Then are three of its keywords. It is built for people to read: the people who asked for a feature can read its scenarios, and each scenario becomes an automated test. One text, two readers, no translation.

The Gherkin structure

A scenario has three sections, and each has one job:

Given sets the scene: the context or state of the system before the behavior under test, the preconditions the scenario needs to make sense.
When is the action or event under test, usually triggered by the user or something outside the system: the one behavior you want to observe.
Then is the outcome that should follow from the When: the results, changes or behavior the test checks for.

An example in Gherkin

Here is one, for signing in:

Feature: Signing in
  A registered customer signs in to see their orders.

  Scenario: Signing in with the correct password
    Given a registered account for "ada@example.com"
    When Ada signs in with the correct password
    Then her session starts

In this scenario:

The Feature line names what the scenarios belong to, with a short description beneath it, often the user story.
The “Given” section establishes the context: an account that already exists.
The “When” section names the one event under test: signing in with the correct password.
The “Then” section names the outcome: a started session. No step names a page or a button, so the scenario can run below the interface as well as in the browser.

Drawn as a timeline, every scenario has the same shape:

The signing-in scenario as a before and an after with one event between them. Given sets the state, When is the one event under test (outlined in violet), and Then is the state that should follow.

More keywords

Beyond Given, When and Then, Gherkin keeps a small vocabulary for shaping scenarios:

Feature: the first primary keyword in a feature file. It names the feature and holds its description, often the user story, above its scenarios.
And: continues the section already under way: a “Given,” “When” or “Then” followed by “And” adds more context, actions or expected outcomes.
But: works exactly like “And”; it reads better before a negative, such as “But the password is not shown.”
Background: the Given steps the scenarios in a feature file share, written once and run before each scenario, so the file stays concise.
Scenario Outline: a parameterized scenario. It runs once for each row of its Examples table, filling each <placeholder> in the steps from that row.
Examples: the table beneath a Scenario Outline; its header row names the placeholders, and each row below it runs the outline once.
Rule: (Gherkin 6 and later) groups the scenarios that illustrate one business rule. A user story’s acceptance criteria can map onto Rules when a Feature holds more than one, and each Rule’s scenarios are its examples.
Tags: a secondary keyword, @, that marks a label such as @checkout, written above a Feature, Rule, Scenario, Scenario Outline or Examples table, so a runner can select or skip what it marks.

The rule behind the examples. A scenario is one example of a rule. When the same rule holds across several cases, a Scenario Outline states it once and an Examples table lists the cases, so the rule reads in one place and each row runs as its own test. One of Module 1’s password-reset criteria, from Translating user needs into user stories, written this way:

Feature: Resetting a password

  Rule: A reset link works once, within 24 hours

    Scenario Outline: Opening a reset link
      Given a reset link issued <age> ago
      And the link <history>
      When Ada opens the link
      Then the link is <result>

      Examples:
        | age      | history        | result   |
        | 1 hour   | was never used | accepted |
        | 1 hour   | was used once  | refused  |
        | 25 hours | was never used | refused  |

A failing row is reported by its own line, with its values filled into the step that failed. Picture a fourth row: a link 25 hours old that was used once. It is refused, and rightly, but the row can’t say which half of the rule refused it: it would still pass with either half broken. That is why each row above changes one thing from the first. The steps name the domain, never the page, so the same table runs against a slice, an endpoint or the browser. The lecture Practical Applications of Functional Programming takes the rule one step further, with property tests that check it across generated inputs.

That is Gherkin: a small, standard vocabulary for how software should behave from the user’s perspective, clear enough for the owner to read and unambiguous enough for a test to run. The next lesson, Writing BDD scenarios, puts the vocabulary to work on a cart scenario, the one Module 4 later builds into a slice.

Given-When-Then (Gherkin) syntax in BDD

The Gherkin structure

An example in Gherkin

More keywords

Marketing

Design

Development

Automation

Local