Gherkin test syntax

When creating a Gherkin test, use a specific structure and syntax to follow established Gherkin rules.

Note: When editing, an error symbol (X) is displayed in lines that contain syntax or logical errors.

Feature section

The feature defines the purpose and goal of the Gherkin test.

  • The feature line starts with the keyword: Feature.
  • A feature contains any number of scenarios.
  • Until the first scenario, enter any text. The text describes the related persona, the feature description, and its importance to that persona.
Copy code
Example: Feature
Feature: Refund an item.
The sales assistant should be able to refund customer purchases.
This is required by law, and is also essential to keep customers happy.

 Feature: Buying items in shopping cart, single user.

Back to top

Background section

You run backgrounds before each scenario. The background defines one set of settings or one context for all scenarios in a feature.

  • The Background section starts with the keyword: Background.
  • Backgrounds can contain steps (Given, When, and Then).
Copy code

Example: Background

Background:
Given: payment security system is up

Back to top

Scenario section

Scenarios describe what the user does and how the application should respond.

  • The Scenario line starts with the keyword: Scenario.
  • A feature can contain many scenarios.
  • Every scenario contains steps, also known as annotations in Gherkin syntax. The steps let you know what to do for the test run. Each scenario can contain many steps of each type.

  • Steps start with Given, When, and Then. Each scenario can contain more than one step.

    Steps Details
    Given statements

    Given steps are preconditions.
    When statements

    When steps describe the action that the user is performing.
    Then statements

    Then steps describe the expected result of the performed action.

Copy code

Example: Scenario

Scenario: Julio buys items in his cart
Given a customer named "Julio Brown"
Given I am logged in as Julio
Given I have at least one item in cart
When I try to buy items in my cart
Then I should be asked for my payment method

Back to top

Scenario outline

The Scenario Outline runs once for each row in the Examples section. You can use the Scenario Outline to parameterize a Gherkin test.

  • Like a Scenario, the Scenario Outline usually contains Given, When, and Then steps.
  • The Given, When, and Then steps contain placeholders (variables) with names listed between the < and > signs.
  • The Examples section contains values for the placeholders to use when the scenario outline runs.
Copy code
Example: Scenario outline
Scenario Outline: Many users buy items in their carts.
Given a customer named "<customer>"
Given I am logged in as "<customer>"
Given I have at least one item in cart
When I try to buy items in my cart
Then I confirm my payment method "<payment>" and proceed to checkout
 
Examples:
| customer | payment |
| Jane Doe | Paypal |
| Jorge Rodriguez | VISA |
| Sally Dunn | VISA |
| Pierre Bisset | American Express |
| Masayoshi Horita | Cash |

Back to top

Localization

You can localize Gherkin test feature files and BDD specs using any spoken language supported by Gherkin. You can write text in any of the supported languages including keywords, inside Gherkin scenarios.

You define the language at the top of the feature file or script, using the standard Gherkin notation, # language.For example, the "fr" notation is an instruction to use the French language.

# language: fr

When you click Add scenario or Add scenario outline, text is added in the language that you specified.

Copy code

Example: Localization

Plan du scénario: 
Soit <param1> 
Quand  <param2>  
Alors  <param3>  
    
Examples:
| param1 | param2 | param3 |
| a      | 1      | 3      |
| b      | 2      | 4      |

If no language is specified, the default, English is used. Admins can set the language using the GHERKIN_SCRIPT_DIALECT parameter. For details, see Configuration parameters.

The last language used is remembered, so that when you create a new document, it will be in your specified language.

Back to top

See also: