Page History
Table of Contents |
---|
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.
Warning | |||||
---|---|---|---|---|---|
| |||||
Starting in version 1.1.1, beware that the repository URL changed to https://maven.getxray.app:443 You must update the repository to the following:
|
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 instanceThe 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
...
Property Name | Required (-Yes,-Optional) | Description | Examples | ||
---|---|---|---|---|---|
xray.jiraURL | Full URL of Jira, including the relative path, if its being used | http://localhost:8080 | |||
xray.resultsFormat | Results format. Available formats:
(more on format specifics in Import Execution Results - REST)
| JUNIT | |||
xray.username | Jira Username | Jira Username | admin | ||
xray.password | Jira Password
| password | |||
xray.projectKey | Jira Project Key Key | MYPROJKEY | |||
xray.testExecKey | Test Execution Issue ID | MYT2-5 | |||
xray.testPlanKey | Test Plan Issue ID | MYT2-54 | |||
xray.testEnvironments | Test Environment | iOS iOS | |||
xray.fixVersion | Fix Version. It supports only one value. | Release 1.0 | |||
xray.revision | Revision | 1234 | |||
xray.testExec-fields.path | (used only for multipart endpoints) | Path to the JSON info file. Used by JIRA to create new issues. | ${basedir}/reports/info.json | ||
xray.surefire.location | Folder with .xml files or xml file to be uploaded | ${basedir}/target/surefire-reports/TEST-com.xpandit.xray.service.ResultImporterTest.xml ${basedir}/target/surefire-reports |
...
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 resultsFormat and is is case-sensitive.
Results Format (xray.resultsFormat) | Description | Support for multipart endpoint |
---|---|---|
JUNIT | JUnit XML output format (more information regarding its endpoints here) | |
TESTNG | TestNG XML output format (more information regarding its endpoints here) |
Uploading the results to a specific endpoint
...
- Build, Test the project and then Upload results results
Code Block |
---|
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 Only
Code Block |
---|
mvn com.xpandit.xray:xray-maven-plugin:<goal-name> |
...
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 via the console with -D option (e.g., -Dxray.projectKey=PROJ).
...
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 instance and the credentials of the JIRA the JIRA user. These properties will be within the Active Profile identified by the id 'MyActiveProfile'.
Code Block | ||||
---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="UTF-8"?>
<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> |
...
Since, in this example, we already defined the JIRA the JIRA address and the credentials in the the settings.xml, when Maven loads the Project's POM, it will pick up the activated profiles from the <activeProfiles> section section of the settings.xml file and inject the properties declared within the profile.
...
- 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
...
Info | ||
---|---|---|
| ||
If the goal was also to upload the results to an existing Test Execution issue, then we should configure the the xray.testExecKey testExecKey property by specifying the Test Execution issue key. |
...
Info | ||
---|---|---|
| ||
This example also describes the usage of the plugin on a standard simple, single-module Project. Note that we declared the plugin inside the the <reporting> tag tag, wherein we identify which version to be used. The tag tag <pluginRepositories> specifies specifies where the plugin should be downloaded from. |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.19.1</version> <configuration> <testFailureIgnore>true</testFailureIgnore> </configuration> </plugin> </plugins> </pluginManagement> </build> <reporting> <plugins> <plugin> <artifactId>maven-surefire-report-plugin</artifactId> </plugin> <plugin> <groupId>com.xpandit.xray</groupId> <artifactId>xray-maven-plugin</artifactId> <version>1.1.0<2</version> </plugin> </plugins> </reporting> <pluginRepositories> <pluginRepository> <id>xpand-plugins</id> <name>xpand-plugins</name> <url>http<url>https://maven.xpand-it.comgetxray.app:443/artifactory/releases</url> </pluginRepository> </pluginRepositories> </project> |
...
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 the xray.resultsFormat and and the xray.surefire.location 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 issues here.
In this example, we configured the following object:
...
- The results file we are uploading is in Junit format
- The results file can be found in this directory: ${basedir}/target/surefire-reports
- The JSON metadata file can be found in this directory: ${basedir}/info.json
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:
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<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 --> <modules> <module>ModuleA</module> </modules> <properties> <!--XRay Properties --> <!-- 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> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.19.1</version> <configuration> <testFailureIgnore>true</testFailureIgnore> </configuration> </plugin> </plugins> </pluginManagement> </build> <reporting> <plugins> <plugin> <artifactId>maven-surefire-report-plugin</artifactId> </plugin> <plugin> <groupId>com.xpandit.xray</groupId> <artifactId>xray-maven-plugin</artifactId> <version>1.0.0</version> </plugin> </plugins> </reporting> <pluginRepositories> <pluginRepository> <id>xpand-plugins</id> <name>xpand-plugins</name> <url>http<url>https://maven.xpand-it.comgetxray.app:443/artifactory/releases</url> </pluginRepository> </pluginRepositories> </project> |
...
Unable to upload the results file: The process is failing with status code code 403
The importing of the execution results file failed and when you check the log, it shows the following:
By default, when you successively uccessively 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 code 403 Forbidden.
You will need to log into Jira via the browser and provide the CAPTCHA.
...
If you are a Jira administrator, you can go to Jira administration > User Management and reset the failed login.
Version History
User Management and reset the failed login.
Version History
- 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:
- 1.1.2 - 20 December 2021
- Bump log4j to version 2.17.0 due to critical security vulnerability:
- 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.