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. The third is a 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 (37 at the time of writing), so that your team can use the keywords in your own language.

There are a few conventions. Single Gherkin source file contains a description of a single feature. Source files have .feature extension.

Gherkin Syntax

Parser divides the input into Feature Introduction and Given-When-Then. When you run the feature the trailing portion of each step is matched to a Ruby code block called Step Definitions. Feature looks like this

Feature: Some terse yet descriptive text of what is desired
  In order to realize a named business value
  As an explicit system actor
  I want to gain some beneficial outcome which furthers the goal

  Scenario: Some determinable business situation
    Given some precondition
      And some other precondition
    When some action by the actor
      And some other action
      And yet another action
    Then some testable outcome is achieved
      And something else we can check happens too

  Scenario: A different situation
      ...

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:
  background:        Background:

  and:               And
  but:               But
  given:             Given
  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.