---
title: "Gherkin (BDD Tests)"
canonical: "https://docs.getxray.app/space/XRAY/159973393/Gherkin%20(BDD%20Tests)"
format: markdown
---
> Macro (toc)
# Overview
Cucumber is a tool that executes plain-text functional descriptions as automated tests. The language that Cucumber understands is called **Gherkin**, which is a business-readable, domain-specific language that describes the software’s behavior without detailing how that behavior is implemented. Gherkin is a line-oriented language that uses indentation to define the structure. Line endings terminate statements (e.g., steps). Either spaces or tabs may be used for indentation (but spaces are more portable). Most lines start with a keyword. Gherkin has become the go-to language of choice for Behaviour-Driven Development or BDD. Gherkin is now supported by many other tools other than Cucumber.
For more information on Cucumber and the Gherkin language, please consult the Wiki and Tutorials at [http://cucumber.io](http://cucumber.io)
## More about Cucumber
Cucumber tests are defined in **.feature** files. Each feature file normally contains all test scenarios for a given software feature. The image below is a simple Cucumber feature file and shows how the different sections are mapped to Jira/Xray entities.
Each **Feature** is mapped to a Requirement in Jira (e.g. Story, Epic, or any other issue type that you consider a Requirement).
The **Background** clause is mapped to a **Precondition** issue in Xray.
Each **Scenario** or **Scenario Outline**, is mapped to a **Test** issue in Xray.
Cucumber Tests (or scenarios) are of two **Scenario Types**:
- ** Scenario:** a set of instructions exclusively composed of constant values, which, when executed by a tool, will only give a static result (e.g., 2 + 3 = 5)
- ** Scenario Outline:** a generic set of instructions containing variables, which, when executed by a tool, will prompt varied results according to the specified input.
In Xray, you can specify the **scenario** directly on the Test issue.
> ℹ️ Please note that custom field **Cucumber Test Type** field is now deprecated since Xray Data Center versions V7.3.0 or higher.
> ℹ️
> ℹ️ This field will **now automatically detect** if the Test has a simple Scenario or a Scenario Outline. Nevertheless, the field will continue to exist and is updated automatically by Xray; this way, you can continue filtering by it when using JQLs.
> Macro (toc)
# Defining Gherkin Tests
In Xray, you can specify the **scenario** directly on the Test issue.
## Using the Issue dialog
When creating or editing Gherkin Tests, you can set the **scenario **directly on the Jira create/edit dialog or page. Just go into the Test Details tab, and choose a Gherkin Test Type. Now you can set the scenario:
## Inline Editing Xray Tests
When viewing Gherkin Test issues in Jira, you can also use inline editing capabilities to set the **scenario**. This prevents full page reloads when modifying these fields.
To edit the **scenario**, you need to use the **Edit Steps **button.
This button will open a dedicated dialog where you can edit the scenario steps using **syntax highlight** and also take full advantage of the **Automated Steps Library** described in the next section.
When done editing the steps, just press **Save** to persist the changes or press **Cancel **to discard them.
> ℹ️ You can only edit the **scenario** field if you have **permission** to edit the Test issue.
# Automated Steps Library
The **Automated Steps Library** provides a centralized place to manage automated steps and allows for easy refactoring of steps (Cucumber/Gherkin only).
**Refactoring** is the keyword and is essential to maintain your automation code base sane.
Since steps are persisted and indexed, they can then be used for autocomplete purposes during the creation/update of Cucumber Scenarios/Backgrounds, facilitating their creation, and avoiding duplicated or messy steps.
A general setting, available in Global Preferences, allows you to globally opt-in or opt-out for this feature. If the Automated Steps Library is not enabled, users can still specify Cucumber Scenarios/Backgrounds, although lacking the autocomplete ability.
## Key concepts
The **Automated Steps Library** provides a per-project organization for all the steps used in automated (Cucumber only) Tests and Pre-Conditions belonging to that project.
In other words, the library provides a centralized point to manage all Gherkin sentences (i.e. the Cucumber "steps" ) of all the Tests and Pre-Conditions of a given project.
Steps are automatically added to the **Automated Steps Library** of a project whenever a Cucumber Test/Pre-Condition of that project is created or updated. Likewise, they're automatically removed if they are not being used by any of those entities, in that project.
Steps are always, and indirectly, automatically created in the library whenever creating/editing a Cucumber Test/Pre-Condition. Steps cannot be created within the **Automated Steps Library** itself.
On the left side of UI, steps can be searched and filtered by labels, while on the right side of the step, content can be edited and saved.
The **Automated Steps Library** provides the means to:
- refactor steps, by easily renaming them (i.e. changing their specification)
- refactor steps, by merging similar steps and avoiding duplicated specifications & associated code
- see which Tests/Pre-Conditions are using a particular step
- label steps, so they can be categorized, in order to ease their management and the step autocompletion during Test/Pre-Condition edition
In the **Automated Steps Library** you cannot:
- create/remove steps (this is done automatically, whenever creating/editing/removing Cucumber Tests/Pre-Conditions)
## Steps
Steps, from the current Automated Steps Library perspective, correspond to Gherkin sentences used by Cucumber Tests/Pre-Conditions (i.e. Cucumber Scenario, Scenario Outline, Background).
Steps are case insensitive and their content is trimmed (i.e. spaces removed at the start/end).
Gherkin reserved keywords (e.g. *Given*, *When*, *Then*, *And*) are not stored in the library, so these two following steps are equally stored as "I have a calculator":
| **Step as written in a Cucumber Test/Pre-Condition** | **Stored step** |
| --- | --- |
| `Given I have a calculator`
`And I have a calculator` | `I have a calculator` |
Steps can be updated/refactored in the Automated Steps Library; they can also be implicitly updated or created whenever editing or creating a Cucumber Test/Pre-Condition.
However, they cannot be created from within the Automated Steps Library UI, in order to avoid dummy/unused steps. In other words, if a step appears in the Automated Steps Library then most probably it is being used by some entity. Exceptions may arise though, especially if the library is disabled somewhere in time or if for some reason Xray was unable to process an update/creation Jira event.
[Integrity Checker](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301668466), or a specific option in the project settings, may be used to force a per-project synchronization of steps, in case you find orphaned or missing steps in the library.
## Learn more
For a fully comprehensive list of the available operations and how to perform them, please check the [Automated Steps Library](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/159907978) page.
# Export to Cucumber
Gherkin Tests in Xray can be exported to **.feature** files ready to be executed in Cucumber. The generated feature files follow the rules defined in [Export Cucumber Features backup](https://getxraydocs.atlassian.net/wiki/pages/createpage.action?spaceKey=xray&title=Export%20Cucumber%20Features%20backup&linkCreation=true&fromPageId=159973393) and take into account the context of the Jira Test issue.
A single Cucumber **feature** file should be generated and prompted for download, unless the target Test is associated with multiple **Requirements**, which, in that case, will prompt a **FeatureBundle** zip file containing a single Cucumber feature file for every Requirement associated with the target Test.
In order to generate a Cucumber feature(s) for a given Test issue:
** Step 1: **Open the Cucumber Test issue view page.** **
**Step 2**: Select **More > Export to Cucumber. **The file will be downloaded to the browser.
