Skip to content

Installation⚓︎

Run the following command to add the plugin to your Cypress project:

1
npm install --save-dev cypress-xray-plugin

This plugin easily handles:

  • Cypress test executions: JavaScript/TypeScript specs
  • Cucumber test executions: Cucumber feature files

Below you will find the two ways to setup the plugin's basics, one for Cypress tests only (when not running Cucumber feature files) and for added Cucumber support.

Cypress tests⚓︎

Modify the setupNodeEvents() function in your Cypress configuration file as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { configureXrayPlugin } from "cypress-xray-plugin";

// ...
    async setupNodeEvents(on, config) {
        await configureXrayPlugin(
            on,
            config,
            {
                jira: {
                    projectKey: "PRJ",         // placeholder value
                    url: "https://example.org" // placeholder value
                }
            }
        );
    }
// ...

Tip

Check out the configuration for more information on how you should configure the plugin to make it work within your infrastructure. You can also shoot a glance at the examples for a more hands-on approach.

Cucumber tests⚓︎

For Cucumber support, this plugin builds upon the cypress-cucumber-preprocessor plugin for executing Cucumber feature files.

With added Xray synchronization, this plugin allows you to automatically upload feature files to Xray when running your Cypress tests and to track their execution results in Xray.

Run the additional following commands to handle Cucumber test executions as well:

1
2
3
npm install --save-dev @badeball/cypress-cucumber-preprocessor
npm install --save-dev @bahmutov/cypress-esbuild-preprocessor
npm install --save-dev cypress-on-fix

Note

Package cypress-on-fix is required for registering multiple event handlers to Cypress's events (see here).

To enable the plugin, modify the setupNodeEvents() function in your Cypress configuration file as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
import createEsbuildPlugin from "@badeball/cypress-cucumber-preprocessor/esbuild";
import createBundler from "@bahmutov/cypress-esbuild-preprocessor";
import { configureXrayPlugin, syncFeatureFile } from "cypress-xray-plugin";
import fix from "cypress-on-fix";

// ...
    async setupNodeEvents(on, config) {
        const fixedOn = fix(on);
        await addCucumberPreprocessorPlugin(fixedOn, config);
        await configureXrayPlugin(
            fixedOn,
            config,
            {
                jira: {
                    projectKey: "PRJ",
                    url: "https://example.org"
                }
                cucumber: {
                    featureFileExtension: ".feature"
                }
            }
        );
        fixedOn("file:preprocessor", async (file) => {
            await syncFeatureFile(file);
            const cucumberPlugin = createBundler({
                plugins: [createEsbuildPlugin(config)],
            });
            return cucumberPlugin(file);
        });
        return config;
    }
// ...

Order matters here!

The Cucumber plugin must be added first so that its event listeners will run before those of the Xray plugin.

1
2
await addCucumberPreprocessorPlugin(fixedOn, config);
await configureXrayPlugin(fixedOn, config, /* ... */);

Otherwise, the Xray plugin won't be able to find the result report generated by the Cucumber plugin, because it won't exist yet.

The highlighted lines are the ones addressing Xray support.

Lines 11-23

Here you should configure the Xray plugin the way you want it to work with your Xray instance. Read this for more information.

Line 25

This line enables upstream synchronization of your feature files with your Xray instance. See here for more information.