Share this page
Gherkin test syntax
When creating a Gherkin test, use a specific structure and syntax to follow established Gherkin rules.
Note: When editing, ALM Octane 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.
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:
Background:
Given: payment security system is up
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
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
Examples:
| customer | payment |
| Jane Doe | Paypal |
| Jorge Rodriguez | VISA |
| Sally Dunn | VISA |
| Pierre Bisset | American Express |
| Masayoshi Horita | Cash |
Localization
ALM Octane 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 ALM Octane 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>
Examples:
| param1 | param2 | param3 |
| a | 1 | 3 |
| b | 2 | 4 |
If no language is specified, ALM Octane uses the default, English. Admins can set the language using the GHERKIN_SCRIPT_DIALECT parameter. For details, see Configuration parameters.
ALM Octane remembers the last language used, so that when you create a new document, it will be in your language.
See also:
