Page History

...

...

You must update the repository to the following:

	<pluginRepositories>
        ...
        <pluginRepository>
			<id>xblend-repo-releases-public</id>
			<url>https://maven.getxray.app:443/artifactory/releases</url>
		</pluginRepository>
	</pluginRepositories>

Overview

Integration with Maven is possible using an open-source Maven plugin sponsored by the Xray team; the Maven plugin is a wrapper that invokes Xray API's to achieve its goals.

This plugin allows uploading test results to Xray, supporting a wide range of test reports/formats; it also allows the import and export of Cucumber/Gherkin scenarios to/from Xray, and thus allow the implementation of the related automation code.

More info can be found on the respective GitHub project. The previous proprietary Maven plugin provided by the Xray team, which only partially supported Xray server/DC, has been deprecated.

Installation and Configuration

This plugin is available on (Maven) Central Repository, which is configured by default in your Maven instalation.

Add the following dependency to your pom.xml, where the <configuration> is optional and should be adapted to your use case.

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>
                <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <projectKey>CALC</projectKey>
                <fixVersion>1.0</fixVersion>
 

In order to make the integration in your Java Maven projects easier, we have developed the Xray-Maven-Plugin. It enables the upload of your Tests directly to Xray with a single Maven command.

The plugin supports single or multi-module projects and multiple test frameworks. With the execution of a single Maven target com.xpandit.xray:xray-maven-plugin:<goal-name>, the plugin will upload the results of the tests to your Jira instance.

List of Available Properties

...

xray.jiraURL

...

http://localhost:8080

...

xray.resultsFormat

...

...

JUNIT

...

xray.username

...

admin

...

xray.password

...

...

password

...

xray.projectKey

...

xray.testExecKey

...

xray.testPlanKey

...

xray.testEnvironments

...

xray.fixVersion

...

xray.revision

...

xray.testExec-fields.path

...

${basedir}/reports/info.json

...

     <reportFormat>junit</reportFormat>
           

...

${basedir}/target/surefire-reports/TEST-com.xpandit.xray.service.ResultImporterTest.xml

${basedir}/target/surefire-reports

...

...

     <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").

...

List of Available Result Formats

Each result format points to a specific Xray REST Endpoint where the results are imported. The result format is configured in the property xray.resultsFormat and is case-sensitive.

...

Results Format (xray.resultsFormat)

...

In this case, the parameters have the xray. prefix.

Configuration made directly on the pom.xml file has higher priority over command line arguments.

There are a set of common configurations related to the Xray details and its authentication. Besides, each task has its own configuration parameters as shown ahead.

Common configurations

The base configurations depend on whether you're using Xray on Jira Cloud or 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, an thus reuses the built-in capabilities provided by Jira itself.

Auhentication is done either using a Jira user's username and password, or eventually a Jira Personal Access Token; none of these are managed directly by Xray but by Jira instead.

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

Xray on Jira cloud uses its own mechanism (i.e. API key pairs) for authenticating requests; in order to obtain the API key (client id + client secret pair) please ask you Jira admin.

How to use

This plugin provides these tasks:

• xray:import-results
• xray:import-features
• xray:export-features

Importing test automation results

In order to import test results, we need to use the xray:import-results task.

 mvn clean compile test xray:import-results

The pom.xml needs to be configured properly (see available configurations). As an alternative to hardcode the configurations, it's also possible to pass them right from the command line as mentioned earlier, or even have some on the pom.xml and another specificed 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

There are two ways of importing results. We can either choose one or the other but not both.

The first one is more simple (recommended for most uses) and also known as "standard" (due to how it is called in terms of REST API) where we provide all or a mix of predefined and common parameters (e.g., projectKey, version) that are enough for most usage scenarios.

There is another way importing results though, that allow us to customize any field on the Test Execution issue or even on the Test issues that may be created; in this case, we need to pass the testExecInfoJson and/or the testInfoJson fields. This approach, also known as "multipart" due to the Xray REST API endpoint it uses, even though more flexible will require us to specify common fields such as the project key, version, and other, within the respective JSON field.

Examples

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

In this example we will:

• upload a JUnit XML report to Xray
• create a Test Execution and assign to a given Jira project, release (i.e. project's FixVersion), and Test Plan

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.0</version>
            <scope>test</scope>
            <configuration>
                <cloud>true</cloud>
                <clientId>215FFD69FE46447280000000000</clientId>

Uploading the results to a specific endpoint

Xray-Maven-Plugin provides two plugin specific goals to upload the results to a specific endpoint:

• xray: uploads the results file to the normal endpoint;
• xray_multipart: uploads the results file to the multipart endpoint;

The goal name must then be specified in maven command so the plugin uploads the results file to the selected Xray endpoint:

• Build, Test the project and then Upload results

mvn clean package surefire:test com.xpandit.xray:xray-maven-plugin:<goal-name>

Or if the project is already built and tested, if you desire only to upload the results:

• Upload results Only

mvn com.xpandit.xray:xray-maven-plugin:<goal-name> 

Maven Project Guidelines

There are three options when configuring the properties listed in the 'List of Available Properties': via settings.xml, via the Project's POM file or via the console with -D option (e.g., -Dxray.projectKey=PROJ).

To understand better how the configurations via settings.xml and the Project POM can be combined, we will be describing an example where we want to import Junit results into Jira. We will assume the Test Cases are already implemented so we only focus on the usage of the this plugin.

In sum the goal is to:

• Generate the Junit XML results file;
• Upload the results to a JIRA instance with a specific address, based on a specific credential info.
• Associate the results to a new Test Execution with Fix Version 'V1.0', in the Test Environment 'Android', in an existing Test Plan issue;

Settings.xml

The plugin properties can be specified in the settings.xml file. In this example, in the <properties> tag, we configured the address of the JIRA instance and the credentials of the JIRA user. These properties will be within the Active Profile identified by the id 'MyActiveProfile'.

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <!-- OTHER CONFS-->
  <profiles>
    <profile>
	<!-- OTHER CONFS-->
      <properties>
        <xray.jiraURL>http://localhost:8080</xray.jiraURL>
        <xray.username>admin</xray.username>
        <xray.password>password</xray.password>
      </properties>
    <id>MyActiveProfile</id>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>MyActiveProfile</activeProfile>
  </activeProfiles>
</settings>

...

The plugin properties listed in 'List of Available Properties' can be scoped to a specific Project, by specifying them in the Project's POM.xml.

Since, in this example, we already defined the JIRA address and the credentials in the settings.xml, when Maven loads the Project's POM, it will pick up the activated profiles from the <activeProfiles> section of the settings.xml file and inject the properties declared within the profile.

So, in this example, we only need to specify the JIRA Project, the Test Plan issue we want to upload the results into and the field values (Test Environment, Fix version and Revision) for the newly created Test Execution.

<xray.projectKey>MYPROJKEY</xray.projectKey>
<xray.testPlanKey>MYPROJKEY-124</xray.testPlanKey>
<xray.testEnvironments>Android<xray.testEnvironments>
<xray.fixVersion>V1.0</xray.fixVersion> 
<xray.revision>Build-1.0</xray.revision>
<xray.resultsFormat>JUNIT</xray.resultsFormat>
<xray.surefire.location>${basedir}/target/surefire-reports</xray.surefire.location>

These properties will instruct the plugin:

• To upload the results to project with key 'MYPROJECTKEY'
• The newly created Test Execution will be associated with the Test Plan with issue key 'MYPROJECTKEY-124'
• The Test Execution will be associated with the Test Environment 'Android'
• The Test Execution's Fix Version custom field will be populated with V1.0
• The Test Executions Revision custom field will be populated with the Revision 'Build-1.0'
• The results file we are uploading is in Junit format
• The results file can be found in this directory: ${basedir}/target/surefire-reports

These properties will then be added to the POM file as illustrated below.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
    <!-- CONF's -->
    <properties>
       
        <!--XRay Properties -->

        <!--IN PROFILE ~.m2/settings.xml-->
        
	<!-- If we want to reuse the configured credentials in settings.xml, then we do not need to configure them here
		<xray.jiraURL></xray.jiraURL>
        <xray.resultsFormat></xray.resultsFormat>
        <xray.username></xray.username>
        <xray.password></xray.password>
	-->
        <xray.projectKey>MYPROJKEY</xray.projectKey>
        <xray.testPlanKey>MYPROJKEY-124</xray.testPlanKey>
        <xray.testEnvironments>Android</xray.testEnvironments>
        <xray.fixVersion>V1.0</xray.fixVersion>
        <xray.revision>Build-1.0</xray.revision>
        <xray.resultsFormat>JUNIT</xray.resultsFormat>
        <xray.surefire.location>${basedir}/target/surefire-reports</xray.surefire.location>
        <!--End Xray Properties -->

    </properties>

    <build>
		<pluginManagement>
        	<plugins>
             <plugin>
   <clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
                <groupId>org.apache.maven.plugins</groupId><projectKey>CALC</projectKey>
                  <artifactId>maven-surefire-plugin</artifactId><fixVersion>1.0</fixVersion>
                  <version>2.19.1</version><testPlanKey>CALC-1200</testPlanKey>
                  <configuration><reportFormat>junit</reportFormat>
                <reportFile>target/junit.xml</reportFile>
      <testFailureIgnore>true</testFailureIgnore>
          </configuration>
        </configuration>
dependency>

        <dependency>
     </plugin>
       <groupId>app.getxray</groupId>
  </plugins>
	      </pluginManagement>
    </build>

<artifactId>xray-maven-plugin</artifactId>
    <reporting>
        <plugins><version>0.6.0</version>
            <plugin><scope>test</scope>
            <configuration>
    <artifactId>maven-surefire-report-plugin</artifactId>
            </plugin><cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
            <plugin>    <jiraUsername>someuser</jiraUsername>
                <groupId>com.xpandit.xray</groupId><jiraPassword>somepass</jiraPassword>
                <artifactId>xray-maven-plugin</artifactId><projectKey>CALC</projectKey>
                <version>1<fixVersion>1.1.2<0</version>fixVersion>
            </plugin>
    <testPlanKey>CALC-1200</testPlanKey>
    </plugins>
    </reporting>

    <pluginRepositories>
    <reportFormat>junit</reportFormat>
    <pluginRepository>
            <id>xpand-plugins</id><reportFile>target/junit.xml</reportFile>
				<abortOnError>true></abortOnError>
            <name>xpand-plugins<</name>configuration>
            <url>https://maven.getxray.app:443/artifactory/releases</url>
        </pluginRepository>
    </pluginRepositories>

</project>

To build, test the Project and upload the results to Jira, we need to execute the command as explained previously in 'Uploading the results to a specific endpoint'.

In this example the goal is to push the results to the normal endpoint, so we choose the 'xray' goal name:

mvn clean package surefire:test com.xpandit.xray:xray-maven-plugin:xray

Importing the execution results with user-defined field values

If we wanted to upload the Junit results to a newly created Test Execution Issue and having control over its fields, for instance by creating it with a custom Issue Summary, then the option is to use the multipart endpoint.

In addition to the xray.resultsFormat and the xray.surefire.location we'll need to configure a JSON file which holds some metadata (used by JIRA to create new issues) and save it in a directory accessible by the plugin. More details regarding how Jira creates new issues here.

In this example, we configured the following object:

{
  "fields": {
    "project": {
      "key": "MYPROJECTKEY"
    },
    "summary": "Test Execution for Junit results",
    "issuetype": {
      "id": "10007"
    }
  }
}

...

<xray.resultsFormat>JUNIT</xray.resultsFormat>
<xray.surefire.location>${basedir}/target/surefire-reports</xray.surefire.location>
<xray.testExec-fields.path>${basedir}/info.json</xray.testExec-field.path>

...

</dependency>

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

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 we will:

• upload mutiple JUnit XML reports to Xray, based on a given regular expression
• create a Test Execution for each imported file, and assign to a given Jira project, release (i.e. project's FixVersion), and Test Plan
• abort the process, if any of the import fails

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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>

        <dependency>
  

...

Lastly, since the goal is to push the results to the multipart endpoint, we run the command by choosing the 'xray_multipart' as the goal name:

mvn clean package surefire:test com.xpandit.xray:xray-maven-plugin:xray_multipart

POM.xml - Multi-Module Project

The Xray-Maven-Plugin can also be used with Multi-Module Projects.

This example describes the usage of the plugin on a Module Project, in this case just one sub-module.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.0</version>
     http://maven.apache.org/maven-v4_0_0.xsd">
     <!-- CONF's -->
	<modules>
 <scope>test</scope>
        	<module>ModuleA</module>	
	</modules>
    <properties><configuration>
       
        <!--XRay Properties -->
 <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
       <!-- If we want to reuse the configured credentials in settings.xml, then we do not need to configure them here
		<xray.jiraURL></xray.jiraURL>
<jiraUsername>someuser</jiraUsername>
                  <xray.resultsFormat></xray.resultsFormat><jiraPassword>somepass</jiraPassword>
        <xray.username></xray.username>
        <xray.password></xray.password>
	<projectKey>CALC</projectKey>
   -->
        <xray.projectKey>MYPROJKEY</xray.projectKey>
        <xray.testPlanKey>MYPROJKEY-124</xray.testPlanKey><fixVersion>1.0</fixVersion>
        <xray.testEnvironments>Android</xray.testEnvironments>        <testPlanKey>CALC-1200</testPlanKey>
        <xray.fixVersion>V1.0</xray.fixVersion>
        <xray.revision>Build-1.0</xray.revision><reportFormat>junit</reportFormat>
        <xray.resultsFormat>JUNIT</xray.resultsFormat>
        <xray.surefire.location>${basedir}/target/surefire-reports</xray.surefire.location>
 
<reportFile>target/*.xml</reportFile>
				<abortOnError>true></abortOnError>
         <!--End Xray Properties -->

    </properties>

 </configuration>
    <build>
		<pluginManagement>
    </dependency>

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

mvn clean compile test xray:import-results

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

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 we will:

• upload a JUnit XML report to Xray
• create a Test Execution and assign to a given Jira project, release (i.e. project's FixVersion)
• additionaly, customize some fields on the Test Execution issue (e.g., set a label, description, a custom field by its id obtainable from Jira administration)

        <dependency>
	 	<plugins>
            	 <plugin>
                  	 <groupId>org.apache.maven.plugins</groupId>
                  	 <artifactId>maven-surefire-plugin</artifactId>
                  	 <version>2.19.1</version>
                   	<configuration><groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
          	 <testFailureIgnore>true</testFailureIgnore>
  <version>0.6.0</version>
            <scope>test</scope>
        	</configuration>
    <configuration>
          	</plugin>
        	<<cloud>true</plugins>
		</pluginManagement>
cloud>
    </build>

    <reporting>
        <plugins><clientId>215FFD69FE46447280000000000</clientId>
            <plugin>
                <artifactId>maven-surefire-report-plugin</artifactId><clientSecret>1c00f8f22f56a8684d7c18cd61470000000</clientSecret>
            </plugin>
            <plugin><reportFormat>junit</reportFormat>
                <groupId>com.xpandit.xray</groupId>
<reportFile>target/junit.xml</reportFile>
				<testExecInfoJson>testExecInfo.json</testExecInfoJson>
				<testInfoJson>testInfo.json</testInfoJson>
				<abortOnError>true></abortOnError>
            </configuration>
    <artifactId>xray-maven-plugin</artifactId>
    </dependency>

        <dependency>
            <version>1<groupId>app.0.0<getxray</version>groupId>
            </plugin><artifactId>xray-maven-plugin</artifactId>
        </plugins>
    <version>0.6.0</version>
        </reporting>

    <scope>test</scope>
    <pluginRepositories>
        <pluginRepository><configuration>
            <id>xpand-plugins</id>
    <cloud>false</cloud>
				<jiraBaseUrl>https://myjiraserver</jiraBaseUrl>
                <name>xpand-plugins<<jiraUsername>someuser</name>jiraUsername>
            <url>https://maven.getxray.app:443/artifactory/releases</url>    <jiraPassword>somepass</jiraPassword>
        </pluginRepository>
    </pluginRepositories>

</project>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0    <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.

{
    "fields": {
    http://maven.apache.org/maven-v4_0_0.xsd">    "project": {
    <!-- CONF's -->
        <name>Module A</name>

"key": "CALC"
    <properties>
    },
    <!--XRay Properties -->
  "summary": "Results for some   <xray.surefire.location>${basedir}/target/surefire-reports</xray.surefire.location>
automated tests",
        "description": "For more info please check [here|https://www.example.com]",
         <!--End Xray Properties -->
    </properties>
</project>

Troubleshooting

Unable to upload the results file: The process is failing with status code 403

The importing of the execution results file failed and when you check the log, it shows the following:

Image Removed

By default, when you successively try to log into Jira with the wrong credentials, the Jira instance will prompt you to provide a CAPTCHA the next time you try to log in. It is not possible to provide this information via the Maven project configuration, so it will fail with status code 403 Forbidden.

You will need to log into Jira via the browser and provide the CAPTCHA.

Image Removed

If you are a Jira administrator, you can go to Jira administration > User Management and reset the failed login.

Image Removed

Version History

"issuetype": {
            "name": "Test Execution"
        },
        "customfield_11805" : [
            "iOS"
        ],
        "fixVersions" :
                [
                 {
                        "name": "1.0"
                 }
                ]
    }
}

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

mvn clean compile test xray:import-results 

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

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 we will:

• upload a JUnit XML report to Xray
• create a Test Execution and assign to a given Jira project, 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)

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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>

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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.

{
    "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.

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

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

mvn clean compile test xray:import-results 

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

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 is to use git (or other versioning control system) as the master to store the corresponding .feature files (more info here). In order to provide visibility of test results for these tests (i.e. gherkin Scenarios), these need to exist in Xray beforehand. Therefore, we need to import/synchronize them to Xray. Note that there is no direct integration; the integration is adhoc, i.e., the following task is run on a local copy of the respository where the .features are stored in.

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

Note: how Xray relates the Scenarios/Background to the corresponding Test or Precondition issues is described in Xray technical documentation (e.g., Xray cloud docs, Xray server/DC docs).

Configuration options

Examples

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

In this example we will:

• process all .feature files in the given folder
• create or update existing Cucumber/Gherkin Test(s) and/or Precondition(s) issues in Xray

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

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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, we need to invoke the respective task.

mvn xray:import-features

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

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

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

In this example we 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 can be done multiple times, to "synchronize" (i.e., update) the scenarios in Xray.

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

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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, we need to invoke the respective task.

mvn xray:import-features

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

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

Exporting/generating Cucumber .feature files from Xray

No matter which worflow 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, 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.

Note: 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, Xray server/DC docs).

Configurations for exporting/generating Cucumber .feature files from Xray

Examples

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

In this example we 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

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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>

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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), we need to invoke the respective task.

mvn xray:export-features

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

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 we 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

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

        <dependency>
            <groupId>app.getxray</groupId>
            <artifactId>xray-maven-plugin</artifactId>
            <version>0.6.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), we need to invoke the respective task.

mvn xray:export-features

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

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

FAQ

• Is this the same maven plugin as the original one made by the Xray team?
  • No. This is a totally new one, made from scratch and open-source.
• If we have questions/support issues, where should those be addressed?
  • It's an open-source project, so it should be handled in the GitHub project and supported by the community. If you want to use the previous, proprietary plugin, you can do so and that has commercial support, if you have a valid license; please note that the proprietary Maven plugin has been deprecated meanwhile.
• Are the underlying APIs the same for Xray server/datacenter and Xray Cloud? Are the available options the same? Are the supported test automation report formats the same?

  • Not exactly. Xray server/datacenter and Xray cloud, even though similar, are actually distinct products; besides Jira server/datacenter and Jira cloud are different between themselves and have different capabilities. This plugin makes use of the available REST APIs for Xray server/datancer and Xray cloud, so you should check them to see exactly what is supported for your environment.

• 1.0.0 - 9 May 2017
  • Import JUnit results: You can import the JUnit results to Xray either as an XML file or a folder with multiple XML files.
• 1.1.0 - xx xx 2019
  • Import TestNG results: You can import the TestNG results to Xray either as an XML file or a folder with multiple XML files;
  • Support for JUnit and TestNG multipart endpoints.
• 1.1.1 - 17 December 2021
  • Bump log4j to version 2.16.0 due to critical security vulnerabilities:
    • https://nvd.nist.gov/vuln/detail/CVE-2021-44228
    • https://nvd.nist.gov/vuln/detail/CVE-2021-45046
    • https://nvd.nist.gov/vuln/detail/CVE-2019-17571
• 1.1.2 - 20 December 2021
  • Bump log4j to version 2.17.0 due to critical security vulnerability:https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-45105