Gherkin test syntax

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

Note: When editing, ValueEdge displays a red X next to any lines with 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.

For example:

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 to all scenarios in a feature.

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

For example:


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.

For example:

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.

For example:

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



| customer | payment |

| Jane Doe | Paypal |

| Jorge Rodriguez | VISA |

| Sally Dunn | VISA |

| Pierre Bisset | American Express |

| Masayoshi Horita | Cash |

Back to top


ValueEdge allows you to 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. For a complete list of the supported languages, see the Gherkin documentation.

You define the language at the top of the feature file or script, using the standard Gherkin notation, # language. In the following example, the "fr" notation tells ValueEdge to use the French language.

# language: fr

When you click Add scenario or Add scenario outline, text will be added in the language that you specified. For example:

Plan du scénario:
Soit <param1>
Quand <param2>
Alors <param3>

| param1 | param2 | param3 |
| a | 1 | 3 |
| b | 2 | 4 |

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

ValueEdge remembers the last language used, so that when you create a new document, it will be in your language.

Back to top

See also: