Skip to content

Cucumber⚓︎

When Cucumber is enabled, you can use the following options to configure the way the plugin works with your feature files.

Mandatory settings⚓︎

featureFileExtension⚓︎

The file extension of feature files you want to run in Cypress. The plugin will use this to parse all matching files to extract any tags contained within them. Such tags are needed to identify to which test issue a feature file belongs (see targeting existing test issues with Cucumber).

Environment variable
CUCUMBER_FEATURE_FILE_EXTENSION
Type
string
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    cucumber: {
        featureFileExtension: ".feature"
    },
});

1
npx cypress run --env CUCUMBER_FEATURE_FILE_EXTENSION=".feature"

Optional settings⚓︎

downloadFeatures⚓︎

Development

This feature will be added in future versions of the plugin.

Set it to true to automatically download feature files from Xray for Cypress to execute.

Note

Enable this option if the source of truth for test cases are step definitions in Xray and Cypress is only used for running tests.

Environment variable
CUCUMBER_DOWNLOAD_FEATURES
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    cucumber: {
        downloadFeatures: true
    },
});

1
npx cypress run --env CUCUMBER_DOWNLOAD_FEATURES=true

prefixes⚓︎

Whenever Cucumber test results or entire feature files are imported, Xray tries to link existing test and precondition Jira issues with the executed/present Cucumber scenarios and backgrounds. The default matching is quite involved (see documentation for Xray server or Xray cloud), but luckily Xray also supports and uses feature file tags. The tags are of the form @[prefix]CYP-123, containing an optional prefix and the issue key. The concrete prefix and whether a prefix is at all necessary depends on your configured prefix scheme in Xray.

The scheme itself can be viewed and configured in Xray:

What if I don't have access to Xray's configuration?

The easiest way to identify the prefixes you need to use is to export an existing test issue to a Cucumber feature file.

If the test issue has preconditions, test sets and requirements (see Xray server or Xray cloud) configured, the exported feature file will automatically contain the full tagging scheme. This scheme can subsequently be used to configure the plugin accordingly.

Example

Let's assume that the Xray tagging scheme is defined as follows:

xray cucumber export and import prefixes

Scenarios then need to be annotated with @TestName:<key> to link the scenarios to an existing test issue in Jira. Correspondingly, backgrounds will need be tagged with @Precondition:<key> inside the first step's comment to link to existing precondition issues.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
Feature: A cool story

    Background:
        #@Precondition:CYP-222
        Given A
        When B
        Then C

    @TestName:CYP-333
    Scenario: Scenario 1
        Given X
        When Y
        Then Z

precondition⚓︎

The prefix for Cucumber background tags.

If left undefined, the plugin will assume that your Xray instance is able to properly parse issue tags without any prefixes, e.g. background tags of the form @CYP-123 instead of something like @Precondition:CYP-123.

Environment variable
CUCUMBER_PREFIXES_PRECONDITION
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    cucumber: {
        prefixes: {
            precondition: "Precondition:"
        }
    },
});

1
npx cypress run --env CUCUMBER_PREFIXES_PRECONDITION="Precondition:"

test⚓︎

The prefix for Cucumber scenario tags.

If left undefined, the plugin will assume that your Xray instance is able to properly parse issue tags without any prefixes, e.g. scenario tags of the form @CYP-123 instead of something like @TestName:CYP-123.

Environment variable
CUCUMBER_PREFIXES_TEST
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    cucumber: {
        prefixes: {
            test: "TestName:"
        }
    },
});

1
npx cypress run --env CUCUMBER_PREFIXES_TEST="TestName:"

uploadFeatures⚓︎

Set it to true to automatically create or update existing Xray issues (steps, labels, ...), based on the feature file executed by Cypress.

Note

Enable this option if the source of truth for test cases are local feature files in Cypress and Xray is only used for tracking execution status/history.

Environment variable
CUCUMBER_UPLOAD_FEATURES
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    cucumber: {
        uploadFeatures: true
    },
});

1
npx cypress run --env CUCUMBER_UPLOAD_FEATURES=true