The Gherkin Language

Behat is a tool to test the behavior of your application, described in a special language called Gherkin. Gherkin is a Business Readable, Domain Specific Language created specifically for behavior descriptions. It gives you the ability to remove logic details from behavior tests.

Gherkin serves as your project’s documentation as well as your project’s automated tests. Behat also has a bonus feature: It talks back to you using real, human language telling you what code you should write.

Tip

If you’re still new to Behat, jump into the Quick Start first, then return here to learn more about Gherkin.

Gherkin Syntax

Like YAML and Python, Gherkin is a whitespace-oriented language that uses indentation to define structure. Line endings terminate statements (called steps) and either spaces or tabs may be used for indentation (we suggest you use spaces for portability). Finally, most lines in Gherkin start with a special keyword:

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

  Additional text...

  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
    ...

The parser divides the input into features, scenarios and steps. Let’s walk through the above example:

  1. Feature: Some terse yet descriptive text of what is desired starts the feature and gives it a title. Learn more about “Features”.

  2. The next three lines (In order to ..., As an ..., I want to ...) provide context to the people reading your feature and describe the business value derived from the inclusion of the feature in your software. These lines are not parsed by Behat and don’t have a required structure.

  3. Scenario: Some determinable business situation starts the scenario and contains a description of the scenario. Learn more about “Scenarios”.

  4. The next 7 lines are the scenario steps, each of which is matched to a pattern defined elsewhere. Learn more about “Steps”.

  5. Scenario: A different situation starts the next scenario and so on.

When you’re executing the feature, the trailing portion of each step (after keywords like Given, And, When, etc) is matched to a pattern, which executes a PHP callback function. You can read more about steps matching and execution in “Defining Reusable Actions”.

Gherkin in Many Languages

Gherkin is available in many languages, allowing you to write stories using localized keywords from your language. In other words, if you speak French, you can use the word Fonctionnalité instead of Feature.

To check if Behat and Gherkin support your language (for example, French), run:

behat --story-syntax --lang=fr

Note

Keep in mind that any language different from en should be explicitly marked with a # language: ... comment at the beginning of your *.feature file:

# language: fr
Fonctionnalité: ...
  ...

This way your features will hold all the information about its content type, which is very important for methodologies like BDD and also gives Behat the ability to have multilanguage features in one suite.

Previous chapter
User Guide
Next chapter
Features and Scenarios