Gherkin

Gherkin is the language that Cucumber understands.
It is a Business Readable, Domain Specific Language
that lets you describe software’s behaviour without detailing how that behaviour is implemented.
Gherkin serves two purposes – documentation and automated tests.
- And a third bonus feature – when it yells in red, don’t be offended – it’s talking to you, telling you what code you should write.

Gherkin’s grammar is defined in the Treetop grammar that is part of the Cucumber codebase.
The grammar exists in different flavours for many Spoken languages,
so that your team can use the Given-When-Then keywords (plus a few more) in your own language.

Syntax Notes

The following notes are an unofficial (and possibly inaccurate) summary of Gherkin syntax. YMMV…

Gherkin “code” is parsed in two stages.
First, a Treetop-based parser divides the input file
into sections (eg, Feature, Scenario) and steps (eg, Given, Then).
The trailing portion of each step is matched by a set of Ruby methods.

Like Python and YAML, Gherkin is a line-oriented language that uses indentation to define structure.
Line endings serve to terminate statements (eg, steps).
Either spaces or tabs may be used for indentation (but spaces are more portable).

Headings

Most Gherkin lines begin with a “heading” (eg, Feature:, Given).
The following text is either unparsed or parsed by regular expressions in a “steps” file.
The heading is separated from the following text by one or more spaces,
which are not passed to the regular expressions.

Gherkin provides parsers for dozens of languages, including (at this writing)
Arabic, Chinese (Simplified), Danish, Dutch, English, Estonian, French, German, Italian,
Japanese, Korean, Lithuanian, LOLCAT, Malay, Norwegian, Polish, Portuguese,
Romanian (with and without diacritical marks), Russian,
Spanish, Swedish, Texan, and Welsh.
This note lists only the English headings;
for corresponding words in other languages, see …/lib/cucumber/languages.yml.

  examples:          Examples:
  feature:           Feature:
  more_examples:     More Examples:
  scenario:          Scenario:
  scenario_outline:  Scenario Outline:

  and:               And
  but:               But
  given:             Given
  given_scenario:    GivenScenario
  then:              Then
  when:              When

Unparsed Lines

Comment lines are allowed anywhere in the file.
They begin with zero or more spaces, followed by a sharp sign (#)
and some amount of text.

Lines of descriptive text may follow a Feature: line.
These must be indented and are not parsed.
The descriptive text may be followed by a Scenario: line or a blank line.