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

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.

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.

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":

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, 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 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 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.

Example

This is a scenario of Cucumber Test with example values noted within the Test Details of the Cucumber Test and associated with a dataset, along with parameterized values at the Test Execution card level (issue type = Test Execution) within a Test Set.

When using the Export to Cucumber option, during the execution of the test, the generated file includes the example data within the Test Details of the Cucumber Test, along with the dataset parameterized values used within the iterations listed as part of the test execution Test Details. If the Cucumber Test is not part of a Test Set, then this issue doesn’t arise; only the Dataset parameterized values appear in the file created from the Export to Cucumber option during the execution of the Cucumber Test.

Please note that if example data within the Cucumber Test and a dataset are associated with the Cucumber Test itself (issue type = Test), then only the dataset parameterized values appear in the file created from the Export to Cucumber option during the execution of a Cucumber Test.