Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท BDD Concepts and Gherkin

Gherkin Syntax: Feature, Scenario, Given, When, Then

A complete tour of Gherkin: Feature, Scenario, Given When Then, And and But, comments, descriptions, tags, indentation and languages, with a runnable parser stand-in.

Gherkin is the structured language of Cucumber. It is deliberately small: about a dozen keywords, a line-based layout and no punctuation rules beyond a few markers. Learn the whole grammar once and you can read any feature file in any Cucumber implementation.

A feature file in full

GHERKIN
# language: en
@billing @smoke
Feature: Account balance
  As an account holder
  I want to see my balance
  So that I know how much I can spend

  Scenario: Deposit increases the balance
    Given an account with a balance of 100 dollars
    When the holder deposits 25 dollars
    Then the balance is 125 dollars

  Scenario: Withdrawal beyond the balance is refused
    Given an account with a balance of 100 dollars
    When the holder withdraws 150 dollars
    Then the withdrawal is refused
    And the balance is 100 dollars

The keywords

Keyword Meaning
Feature: Names the capability and starts the file. One feature per file.
Scenario: (or Example:) One concrete example of behavior.
Given The starting context. State, not an action.
When The event or action under test. Usually one per scenario.
Then The expected observable outcome.
And, But Continue the previous step type, for readability.
* A neutral bullet that can replace any step keyword.
Background: Steps shared by all scenarios (next lesson).
Scenario Outline: A scenario template with Examples: (chapter 4).
Rule: Groups scenarios under one business rule (next lesson).
""" and | Doc strings and data tables (chapter 4).
@tag Labels for filtering and hooks.
# A comment line.

Feature

The line after Feature: is the title. Everything up to the first Scenario: is free-text description. Cucumber ignores it, which makes it the right place for context. Many teams use the "As a / I want / So that" user-story format there; others write a short paragraph on the business rule. Use whichever tells a newcomer why the feature exists.

Scenario

A scenario is a titled sequence of steps. The title should state the behavior ("Withdrawal beyond the balance is refused"), not the mechanism ("Test withdraw method"). Scenarios must be independent: no scenario may rely on another having run first.

Given, When, Then

The three step types have meanings that readers rely on:

  • Given sets the stage. It describes a situation that already holds, in the present or past tense ("an account with 100 dollars"). Given steps should not click anything the user would click; they put the system in the starting state, ideally by the fastest route (a database setup, an API call).
  • When is the single action whose consequence you are examining ("the holder withdraws 150 dollars").
  • Then asserts an outcome the user or a downstream system could observe ("the balance is 100 dollars").

Cucumber itself does not enforce these roles; it matches by sentence text. But a scenario whose Then steps change state, or whose Given steps assert, confuses everybody.

And, But and the star

And and But repeat the previous keyword to avoid "Given... Given...". But signals a contrast ("But the balance is unchanged"). Both are cosmetic. The * is a bullet that works anywhere; it shines in long lists of preconditions:

GHERKIN
Scenario: Check the starting inventory
  Given the shop sells
    * a book
    * a lamp
    * a mug

Comments, tags and descriptions

A line starting with # is a comment. The only special comment is # language: fr, which must be on the very first line and sets the language of keywords. Cucumber ships translations for more than 70 languages; # language: de accepts Funktionalitรคt, Szenario, Angenommen, Wenn, Dann.

Tags start with @. They precede a Feature, Scenario, Scenario Outline, Rule or Examples and let you select scenarios at run time or attach hooks. The full treatment comes in the chapter on hooks and tags; for now know that @smoke marks a group.

Indentation and layout

Gherkin does not use indentation to determine meaning. The two-space convention above is only for readers. What matters is that every keyword sits at the start of its line (after any whitespace) and every step is on its own line. Long sentences should not wrap onto the next line, because the second line would be parsed as a new (invalid) line.

A parser stand-in

The runner has to turn this text into structure. The stand-in below is a tiny tokenizer: it classifies every line (feature, scenario, step, comment, tag, description, blank) and reports the structure. It uses the same line-by-line approach as the real parser, which makes the grammar feel less magical. Paste your own text into the text block.

Java Stand-in: classify every line of a feature

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The last line is flagged as UNRECOGNISED: a wrapped step line is not a step. The real parser would report a syntax error with the line number, so keep every step on one line.

Validating structure

Beyond syntax, teams agree conventions: one When per scenario, Then after When, no Then before any When. A second stand-in checks that style. It does not exist in Cucumber itself; linters such as gherkin-lint do this kind of work.

Java Stand-in: a tiny Gherkin style checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Writing steps people can read

A few conventions make feature files pleasant:

  • Write steps in the third person, present tense: "the holder deposits 25 dollars", not "I deposit".
  • Prefer domain words to technical ones: "the order is shipped", not "the status column is set to 4".
  • Quote string values in double quotes so the step expression can tell them from numbers: the user "maria" signs in.
  • One fact per step. "Given a user named Maria with 3 orders and a gold plan" hides three facts; split or restructure.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the free text between 'Feature:' and the first scenario do?

    Descriptions are free text; use them to explain the purpose and rules of the feature.
  2. 2. Which step keyword describes the single action under test?

    When is the event whose consequence the scenario examines.
  3. 3. A long step sentence is wrapped onto a second line. What happens?

    Gherkin is line-based: each step must be complete on one line.
  4. 4. Where must the '# language: fr' comment appear?

    The language header is only honored on the first line.
  5. 5. What is the difference between And and But?

    Both are cosmetic and keep the previous keyword's meaning.

Summary

  • Gherkin is line-based: Feature, Scenario, steps, plus tags, comments, descriptions, Background, Outline and Rule.
  • Given sets context, When is the action, Then checks the outcome; And, But and * are readability aids.
  • Indentation is cosmetic, but every step must be one complete line.
  • Write in third person, domain vocabulary and with quoted strings.
  • Cucumber matches steps by text, so roles of Given, When and Then are a convention you must keep yourself.

Next: Background, Rules and Organizing Scenarios