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.

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.

    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