---
title: "Integration with Maven"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44568365/Integration%20with%20Maven"
format: markdown
---
> Macro (ui-expand)
> 
> > Macro (toc)

# Introduction

[Maven](https://maven.apache.org/) is a <span style="color: #4d5156">software project management and comprehension tool.</span>

The Xray integration with Maven is possible using an open-source Maven plugin sponsored by the Xray team. This Maven plugin is a wrapper that invokes Xray APIs to achieve its goals.

This plugin allows you to upload Test results to Xray, supporting a wide range of Test reports and formats. It also enables the import and export of Cucumber/Gherkin scenarios to and from Xray, facilitating the implementation of related automation code.

Support for the open-source plugin is handled through the [respective GitHub project](https://github.com/Xray-App/xray-maven-plugin), in line with regular open-source practices. Users can report issues and suggest ideas, but contributions are also encouraged. Please note that there is no service-level agreement for issues raised on this open-source project, as they will be handled on a best-effort basis by the community.

The [previous proprietary Maven plugin](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301501875) provided by the Xray team, which only partially supported Xray Server/DC, has been deprecated. If you are still using the previous proprietary Maven plugin, you will continue to have access to official support. However, please be aware that it has been deprecated, and it is highly recommended to switch to the new plugin.

The Xray Maven plugin offers a powerful integration for managing [Automated Tests within Jira](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565278), making it easier to manage Test automation results and Cucumber/[Gherkin](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565320) scenarios in Xray. By following the installation and configuration instructions above, you can streamline your Testing process and take full advantage of Xray's capabilities.

# Installation and Configuration

<span style="color: #24292f">This plugin is </span>[<span style="color: #24292f">available on the (Maven) Central Repository</span>](https://maven.apache.org/plugins/maven-install-plugin/)<span style="color: #24292f">, which is configured by default in your Maven installation.</span>

Add the following dependency to your `pom.xml`. The `<configuration>` section is optional and should be adapted to your specific use case.

> ❌ Ensure that you are using Xray on Jira Cloud or Xray on Jira Server/Data Center, as these are two similar but distinct products with slightly different capabilities.


##### **pom.xml sample**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
            </configuration>
        </dependency>
```

Configuration parameters (e.g., `reportFormat`) can also be specified from the command line using `-D` (e.g., `-Dxray.reportFormat=junit`). In this case, the parameters have the `xray.` prefix.

Configuration set directly in the `pom.xml` file has higher priority over command-line arguments.

There is a set of common configurations related to Xray details and their authentication. Additionally, each task has its own configuration parameters, as shown below.

## Common Configurations

The base configurations depend on whether you're using Xray on Jira Cloud or Xray on Jira Server/Datacenter.

### Xray Server/Datacenter Users

(i.e., using Xray on Jira server/datacenter)

Xray on Jira Server/Datacenter is built on top of [Jira's REST API](https://developer.atlassian.com/cloud/jira/platform/rest/), reusing the built-in capabilities provided by Jira.

Authentication is handled either by using a Jira user's username and password or via a [Jira Personal Access Token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) (PAT). These credentials are managed by Jira, not directly by Xray.

| **Parameter** | **Command line parameter** | **Description** | **Example** |
| --- | --- | --- | --- |
| `cloud` | `xray.cloud` | Set to false if not using Xray cloud (default: false) | false |
| `jiraBaseUrl` | `xray.jiraBaseUrl` | Jira server/DC base URL | http://10.0.0.1/ |
| `jiraUsername` | `xray.jiraUsername` | Username of Jira user to use on API calls | someuser |
| `jiraPassword` | `xray.jiraPassword` | Password of Jira user to use on API calls | somepass |
| `jiraToken` | `xray.jiraToken` | Jira PAT (Personal Access Token) used instead of username/password | - |
| `ignoreSslErrors` | `xray.ignoreSslErrors` | Ignore SSL errors, e.g., expired certificate (default: false) | - |
| `timeout` | `xray.timeout` | Connection timeout in seconds (default: 50) | - |

### Xray Cloud Users 

(i.e., using Xray on Jira cloud)

Xray on Jira Cloud uses its [own mechanism (i.e., API key pairs)](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44838245) for authenticating requests; contact your Jira admin to obtain the API key (client ID + client secret pair).

> ℹ️ If you are using [Data Residency capabilities](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565771) supported by Jira and Xray in the Cloud, you can fine-tune Xray's REST API base URL to use a specific region. While this is optional, it can improve latency on API calls and overall performance when using this plugin.
> ℹ️ 
> ℹ️ In case your location is Europe and you move Xray Data to a European location ( like Europe - Frankfurt) you may experience improved performance on loading information from Xray.


| **Parameter** | **Command line parameter** | **Description** | **Example** |
| --- | --- | --- | --- |
| `cloud` | `xray.cloud` | Set to `true` if using Xray cloud (default: `false`) | true |
| `clientId` | `xray.clientId` | Client ID of the API key configured on Xray Cloud | xxxx... |
| `clientSecret` | `xray.clientSecret` | Client secret of the API key configured on Xray Cloud | xxxx... |
| `cloudApiBaseUrl` | `xray.cloudApiBaseUrl` | Xray Cloud REST API base URL (default: https://xray.cloud.getxray.app/api/v2); useful for deployments having data residency. Check possible values in the [API docs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565892) | https://eu.xray.cloud.getxray.app/api/v2 |
| `timeout` | `xray.timeout` | Connection timeout in seconds (default: 50) | 50 |

## Using the Plugin

The plugin provides these tasks:

- `xray:import-results`
- `xray:import-features`
- `xray:export-features`

### Importing Test Automation Results

To import Test results, use the `xray:import-results` task.

` mvn clean compile test xray:import-results`

Ensure the `pom.xml` is configured properly (see available configurations). Alternatively, you can pass configurations directly from the command line as mentioned earlier, or have some in the `pom.xml` and others specified through command-line parameters.

` mvn clean compile test xray:import-results -Dxray.reportFormat=junit -Dxray.reportFile=results/junit.xml`  


> ℹ️ Xray Server/DC and Xray Cloud support mostly the same formats. Please check the respective product documentation as restrictions may apply.

#### Configuration Options

<span style="color: #24292f">There are two ways of importing results. You can either choose one or the other, but not both.</span>

##### <span style="color: #24292f">First Way</span>

The first method is simpler (recommended for most users) and is also known as "standard" (due to how it is referred to in terms of the REST API). This method provides a mix of predefined and common parameters (e.g., projectKey, version) that are sufficient for most usage scenarios.

| **Setting** | **Command line parameter** | **Description** | **Mandatory/Optional** | **Example** |
| --- | --- | --- | --- | --- |
| `reportFormat` | `xray.reportFormat` | Format of the report (JUnit, TestNG, NUnit, Nunit, Xunit, Robot, Cucumber, Behave) | Mandatory | JUnit |
| `reportFile` | `xray.reportFile` | File with the test results (relative or absolute path); it can also be a directory (all .xml files will be imported in this case); finally, it can also be a regex that applies to the current working directory | Mandatory | target/junit.xml |
| `projectKey` | `xray.projectKey` | Key of the Jira project where to import the results | Mandatory (doesn't apply to Cucumber or Behave report formats, for legacy reasons) | CALC |
| `testExecKey` | `xray.testExecKey` | Issue key of the [Test Execution](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565117), in case you want to update the results on it | Optional | CALC-2 |
| `testPlanKey` | `xray.testPlanKey` | Issue key of the [Test Plan](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565153) to link the results to | Optional | CALC-1 |
| `version` | `xray.version` | A version of the SUT that corresponds to the Jira project version/release; it will be assigned to the Test Execution issue using the *fixVersion(s)* field | Optional | 1.0 |
| `revision` | `xray.revision` | Source code revision or a build identifier | Optional | 123 |
| `testEnvironment` | `xray.testEnvironment` | Usually, a [Test environment](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565129) name/identifier (e.g., browser vendor, OS version, mobile device, Testing stage); multiple Test environments may be specified by using ";" as the delimiter | Optional | chrome |
| `testInfoJson` | `xray.testInfoJson` | Path to a JSON file containing attributes to apply on the Test Issues that may be created, following the Jira Issue update syntax | Optional | - |
| `testExecInfoJson` | `xray.testExecInfoJson` | Path to a JSON file containing attributes to apply on the Test Execution Issue that may be created, following the Jira Issue update syntax | Optional | - |
| `abortOnError` | Abort if multiple results are being imported, and exit with an error if uploading results fails | optional | - | - |

##### <span style="color: #24292f">Second Way</span>

The second method is more flexible and powerful, allowing you to import any kind of Test results, from simple to complex ones (e.g., with multiple [Test steps](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565316)). This method provides flexibility but also requires additional knowledge about the specific Test report format and the associated REST API used for importing the test results.

This method utilizes an external task `xray:import` that requires the format to be either specified on the command line or defined in the `pom.xml`.

| **Setting** | **Command line parameter** | **Description** | **Mandatory/Optional** | **Example** |
| --- | --- | --- | --- | --- |
| `reportFormat` | `xray.reportFormat` | Format of the report (JUnit, TestNG, NUnit, Nunit, Xunit, Robot, Cucumber, Behave) | Mandatory | JUnit |
| `reportFile` | `xray.reportFile` | File with the Test results (relative or absolute path); it can also be a directory (all .xml files will be imported in this case); finally, it can also be a regex that applies to the current working directory | Mandatory | target/junit.xml |
| `testInfoJson` | `xray.testInfoJson` | Path to a JSON file containing attributes to apply to the Test Issues that may be created, following the Jira Issue update syntax | Optional | testInfo.json |
| `testExecInfoJson` | `xray.testExecInfoJson` | Path to a JSON file containing attributes to apply on the Test Execution Issue that may be created, following the Jira Issue update syntax | Optional | testExecInfo.json |
| `abortOnError` | abort, if multiple results are being imported, and exit with an error if uploading results fails. `False` by default. | Optional | - | true |

#### Examples

##### Importing a file with Junit XML test results to Xray; assign them to a project, version, and Test Plan

In this example you will:

- Upload a JUnit XML report to Xray.
- Create a Test Execution and assign it to a given Jira project, release (i.e. project's FixVersion), and Test Plan.

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
                <testPlanKey>CALC-1200</testPlanKey>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
                <testPlanKey>CALC-1200</testPlanKey>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

To import the Test results, you need to invoke the respective task.

```shell
mvn clean compile test xray:import-results
```

##### Import multiple Junit XML test results to Xray; assign them to a project, version, and Test Plan

In this example, you will:

- Upload multiple JUnit XML reports to Xray, based on a given regular expression.
- Create a Test Execution for each imported file, and assign it to a given Jira project, release (i.e. project's FixVersion), and Test Plan.
- Abort the process, if any of the imports fails.

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
                <testPlanKey>CALC-1200</testPlanKey>
                <reportFormat>junit</reportFormat>
                <reportFile>target/*.xml</reportFile>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
                <testPlanKey>CALC-1200</testPlanKey>
                <reportFormat>junit</reportFormat>
                <reportFile>target/*.xml</reportFile>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

To import the Test results, we need to invoke the respective task.

```shell
mvn clean compile test xray:import-results
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:import-features -Dxray.reportFile=target/*.xml
```

##### Import a file with Junit XML test results to Xray, and customize fields on the corresponding Test Execution Issue

In this example, you will:

- Upload a JUnit XML report to Xray.
- Create a Test Execution and assign it to a given Jira project, release (i.e. project's FixVersion).
- Additionally, customize some fields on the Test Execution Issue (e.g., set a label, description, or a custom field by its ID - obtainable from Jira administration).

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
				<testExecInfoJson>testExecInfo.json</testExecInfoJson>
				<testInfoJson>testInfo.json</testInfoJson>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
				<testExecInfoJson>testExecInfo.json</testExecInfoJson>
				<testInfoJson>testInfo.json</testInfoJson>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

The `testExecInfo.json` contents are as follows:

##### **testExecInfo.json sample**

```javascript
{
    "fields": {
        "project": {
            "key": "CALC"
        },
        "summary": "Results for some automated tests",
        "description": "For more info please check [here|https://www.example.com]",
        "issuetype": {
            "name": "Test Execution"
        },
        "customfield_11805" : [
            "iOS"
        ],
        "fixVersions" :
                [
                 {
                        "name": "1.0"
                 }
                ]
    }
}

```

To import the Test results, you need to invoke the respective task.

```shell
mvn clean compile test xray:import-results 
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:import-features -Dxray.reportFile=target/*.xml -Dxray.testExecInfoJson=testExecInfo.json
```

##### Import a file with Junit XML test results to Xray, and customize fields on corresponding Test issues

In this example, you will:

- Upload a JUnit XML report to Xray.
- Create a Test Execution and assign it to a given Jira project, or release (i.e. project's FixVersion).
- Customize some fields on the Test Issues (e.g., set a label) that will be provisioned the first time results are imported (if the Tests don't already exist).

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
				<testExecInfoJson>testExecInfo.json</testExecInfoJson>
				<testInfoJson>testInfo.json</testInfoJson>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
				<testExecInfoJson>testExecInfo.json</testExecInfoJson>
				<testInfoJson>testInfo.json</testInfoJson>
				<abortOnError>true></abortOnError>
            </configuration>
        </dependency>
```

The `testExecInfo.json` contents are as follows:

##### **testExecInfo.json sample**

```javascript
{
    "fields": {
        "project": {
            "key": "CALC"
        },
        "summary": "Test Execution for some automated tests",
        "issuetype": {
            "name": "Test Execution"
        },
        "fixVersions" :
                [
                 {
                        "name": "1.0"
                 }
                ]
    }
}
```

The `testInfo.json` contents are as follows:

##### **testInfo.json sample**

```javascript
{
    "fields": {
        "description": "Automated Test",
        "labels": [
            "Automation"
        ]
    }
}
```

To import the test results, you need to invoke the respective task:

```shell
mvn clean compile test xray:import-results 
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:import-features -Dxray.reportFile=target/*.xml -Dxray.testExecInfoJson=testExecInfo.json -Dxray.testInfoJson=testInfo.json
```

### Importing/Synchronizing Cucumber .feature Files to Xray

One of the possible workflows for [using Gherkin-based frameworks](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565237/Testing+in+BDD+with+Gherkin+based+frameworks+e.g.+Cucumber#Pure-VCS-based-workflow) is to use Git (or another versioning control system) as the master to store the corresponding .feature files. To provide visibility of Test results for these Tests (i.e. Gherkin scenarios), these need to exist in Xray beforehand. Therefore, you need to import/synchronize them to Xray.

There is no direct integration; the integration is ad-hoc, i.e., the following task is run on a local copy of the repository where the .features are stored.

` mvn clean compile test xray:import-features -Dxray.inputFeatures=features/`

> ℹ️ How Xray relates the Scenarios/Background to the corresponding [Test](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565156) or [Precondition](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565159) Issues is described in Xray technical documentation (e.g., [Xray cloud docs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577091), [Xray server/DC docs](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301698724)).

#### Configuration Options

| **Parameter** | **Command line parameter** | **Description** | **Mandatory/Optional** | **Example** |
| --- | --- | --- | --- | --- |
| `projectKey` | `xray.projectKey` | Key of Jira project where to import the Cucumber Scenarios/Backgrounds as Test and Precondition issues | Mandatory (if projectId not used) | CALC |
| `projectId` | `xray.projectId` | **Xray Cloud only**: ID of Jira project where to import the Cucumber Scenarios/Backgrounds as Test and Precondition Issues | Mandatory (if projectKey not used) | 1000 |
| `source` | `xray.source` | - | Optional; only applies to Xray cloud |  |
| `testInfoJson` | `xray.testInfoJson` | Path to a JSON file containing attributes to apply to the Test Issues that may be created, following the Jira Issue update syntax | Optional | - |
| `precondInfoJson` | `xray.precondInfoJson` | Path to a JSON file containing attributes to apply to the Precondition Issues that may be created, following the Jira Issue update syntax | Optional | - |
| `inputFeatures` | `xray.inputFeatures` | Either a .feature file, a directory containing .feature files, or a zipped file containing .feature files | Mandatory | features/ |
| `updateRepository` | `xray.updateRepository` | Create folder structure in the [Test Repository](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565166) based on the folder structure in the .zip file containing the .feature files; default is false. Only supported on Xray Server/DC. | Optional | true |

#### Examples

##### Importing Scenarios and Backgrounds from existing .feature files in a folder to Xray

In this example, you will:

- Process all .feature files in the given folder.
- Create or update existing Cucumber/Gherkin Test(s) and/or Precondition(s) Issues in Xray.

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <featuresPath>features/</featuresPath>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <featuresPath>features/</featuresPath>
            </configuration>
        </dependency>
```

To import the Gherkin scenarios, you need to invoke the respective task.

```shell
mvn xray:import-features
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:import-features -Dxray.featuresPath=features/
```

##### Importing Scenarios and Backgrounds from existing .feature files in a zipped file to Xray

In this example, you will:

- Process all .feature files in the given .zip file.
- Create or update existing Cucumber/Gherkin Test(s) and/or Precondition(s) Issues in Xray.

This can be done just once to import the Test scenarios to Xray or it can be done multiple times, to "synchronize" (i.e., update) the scenarios in Xray.

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <featuresPath>gherkin_features.zip</featuresPath>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <featuresPath>gherkin_features.zip</featuresPath>
            </configuration>
        </dependency>
```

To import the Gherkin scenarios, you need to invoke the respective task.

```shell
mvn xray:import-features
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:import-features -Dxray.featuresPath=gherkin_features.zip
```

### Exporting/Generating Cucumber .feature Files from Xray

No matter which workflow you decide to use for dealing with Gherkin-based tests (e.g., Cucumber .feature files and corresponding Scenarios), as part of that workflow comes the need to extract/generate the .feature files based on Scenarios or Backgrounds detailed in Xray using Test or Precondition Issues. This plugin provides a task for this purpose. It will download/generate .feature files to a local folder from existing information in Xray. The .feature and Scenario elements will be properly tagged with info from Xray.

` mvn xray:export-features -Dxray.issueKeys=CALC-1,CALC-2 -Dxray.outputDir=features/`

Files on the destination folder will be overwritten; however, if this directory contains other information (including other .feature files) you may need to remove them before generating the .feature files into this directory.

> ℹ️ How Xray generates the .feature files with the Scenarios/Background from existing Test or Precondition Issues is described in Xray technical documentation (e.g., [Xray cloud docs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565307), [Xray server/DC docs](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301406470)).

#### Configurations for Exporting/Generating Cucumber .feature Files from Xray

| **Parameter** | **Command line parameter** | **Description** | **Mandatory/optional** | **Example** |
| --- | --- | --- | --- | --- |
| `issueKeys` | `xray.issueKeys` | Issue keys of direct or indirect references to Cucumber/Gherkin tests/scenarios (e.g., Test issue keys), delimited by comma | Mandatory (optional if *filterId* is used instead) | CALC-1,CALC-2 |
| `filterId` | `xray.filterId` | ID of the Jira filter containing direct or indirect references to Cucumber/Gherkin tests/scenarios | Mandatory (optional if *issueKeys* is used instead) | 12000 |
| `outputDir` | `xray.outputDir` | Output directory where the .feature files should be extracted to | Mandatory | features/ |

#### Examples

##### Export Cucumber/Gherkin test scenarios from Xray to a local directory, based on the given Issue keys

In this example, you will:

- Export two existing Cucumber/Gherkin Test Issues from Xray; these Issue keys could also be referring to story Issues, Test Plans, etc. (Xray will find out the related Cucumber/Gherkin Tests and export those).
- Generate the corresponding .feature file(s), on a local directory.

##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <issueKeys>CALC-1,CALC-2</issueKeys>
                <outputDir>features/</outputDir>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <issueKeys>CALC-1,CALC-2</issueKeys>
                <outputDir>features/</outputDir>
            </configuration>
        </dependency>
```

To export the Cucumber/Gherkin Tests and generate the corresponding .feature file(s), you need to invoke the respective task.

```shell
mvn xray:export-features
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:export-features -Dxray.issueKeys=CALC-1,CALC-2 -Dxray.outputDir=features/
```

##### Export Cucumber/Gherkin test scenarios from Xray to a local directory, based on the given Jira filter ID

In this example, you will:

- Export two existing Cucumber/Gherkin Test Issues from Xray, based on a given Jira filter ID; the filter can include Tests directly or related Issues (e.g., story Issues, Test Plans, etc ), and Xray will then find out the related Cucumber/Gherkin Tests and export those.
- Generate the corresponding .feature file(s), on a local directory.


##### **Xray Cloud: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <filterId>12345</filterId>
                <outputDir>features/</outputDir>
            </configuration>
        </dependency>
```

##### **Xray server/datacenter: pom.xml snippet**

```xml
        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.8.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <jiraUsername>someuser</jiraUsername>
                <jiraPassword>somepass</jiraPassword>
                <filterId>12345</filterId>
                <outputDir>features/</outputDir>
            </configuration>
        </dependency>
```

To export the Cucumber/Gherkin tests and generate the corresponding .feature file(s), you need to invoke the respective task.

```shell
mvn xray:export-features
```

You could also specify some of these options from the command line instead of having them hardcoded in the `pom.xml` file.

```shell
mvn xray:export-features -Dxray.filterId=12345 -Dxray.outputDir=features/
```

# FAQs

> Macro (ui-steps)
> 
> > Macro (legacy-content)
> 
> > Macro (legacy-content)
> 
> > Macro (legacy-content)


<details>
<summary>Support/Troubleshooting</summary>

If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://docs.getxporter.app/space/XPORTER/23102936).
</details>