External execution results from either automated and manual Tests can be imported to Jira. This operation may be done in one of two ways:
- Manually, using the Import Execution Results action accessible from the Test Execution issue screen
- via the REST API to integrate with Continuous Integration (CI) platforms or other external execution processes. Please refer to the Xray REST API.
Supported Import Formats
Xray supports the following formats for importing execution results:
- Cucumber JSON output format
- JUnit XML output format
- NUnit XML output format
- Xray JSON format
Cucumber JSON output format
The Cucumber tool is capable of generating multiple reports for an execution. In order to import the execution results to Xray, Cucumber must generate a JSON output (example here) using the following arguments:
JUnit XML output format
Xray supports a JUnit XML format for importing execution results.
Xray-JUnit XML extension format
Users are also able to import JUnit results using the Xray extended format.
This format adds the following property elements:
For more detailed information, visit the Xray App GitHub repository: https://github.com/Xray-App/xray-junit-extensions.
NUnit v3.0 XML output format
Xray supports an NUnit v3.0 XML format for importing execution results.
NUnit v2.6 XML output format
Xray supports an NUnit v2.6 XML format for importing execution results.
Xray JSON format
Xray also provides a proprietary JSON format for importing execution results.
Although Xray supports multiple report formats used by different testing frameworks/runners (e.g. JUnit, NUnit, xUnit, TestNG, Cucumber, Robot Framework), there are scenarios where using these formats is not an option like:
- Importing results for manual Tests;
- Using a testing framework report that is not supported by Xray;
- Having your own testing framework;
- Limited support of existing formats to import detailed execution results back into Jira.
Importing Execution Evidence
Creating new Test Execution issues
The info object allows you to specify specific execution information when creating new Test Execution issues.
Importing results to Manual Tests
You can import manual Test execution results using the steps element for specifying the Test step results.
|testExecutionKey||The test execution key where to import the execution results|
|info||The info object for creating new Test Execution issues (link)|
|tests||The Test Run result details (link)|
"info" object - Test Execution issue
You can specify which Test Execution issue to import the results by setting the test execution key on the testExecutionKey property. Alternatively, you can create a new Test Execution issue for the execution results and specify the issue fields within the info object.
|project||The project key where the test execution will be created|
|summary||The summary for the test execution issue|
|description||The description for the test execution issue|
|version||The version name for the Fix Version field of the test execution issue|
|revision||A revision for the revision custom field|
|user||The username for the Jira user who executed the tests|
|startDate||The start date for the test execution issue|
|finishDate||The finish date for the test execution issue|
|testPlanKey||The test plan key for associating the test execution issue|
|testEnvironments||The test environments for the test execution issue|
"tests" object - Test Run details
The test run details object allows you to import any detail about the execution itself. All Xray test types are supported.
It is possible to import a single result (the test object itself with the "steps" (Manual tests) or "examples" (BDD tests)) or multiple execution results into the same Test Run (data-driven testing) using the "iterations" array.
|testKey||The test issue key|
|testInfo||The testInfo element (link)|
|start||The start date for the test run|
|finish||The finish date for the test run|
|comment||The comment for the test run|
|executedBy||The user id who executed the test run|
|assignee||The user id for the assignee of the test run|
|status||The test run status (PASSED, FAILED, EXECUTING, TODO, custom statuses ...)|
|steps||The step results (link)|
|examples||The example results for BDD tests (link)|
|iterations||The iteration containing data-driven test results (link)|
|defects||An array of defect issue keys to associate with the test run|
|evidence||An array of evidence items of the test run (link)|
|customFields||An array of custom fields for the test run (link)|
"testInfo" object - Creating Test issues
It is possible to create new test issues when importing execution results using the Xray JSON format. For this, a testInfo element must be provided in order for Xray to create the issues.
If it is the first time you are importing an execution with a testInfo, Xray will create the tests automatically. Subsequent executions will reuse the same test issues.
Xray will first try to match test issues by the testKey if present. Otherwise, Manual or BDD tests are matched by summary whilst Generic tests are matched using the generic definition field, within the same project.
Any changes to the testInfo element will update the test issue specification in Jira.
If the match field (summary or definition) is changed, Xray will search for another issue and will create a new test case, or update an existing test case if no one is found. If you need to change the summary or the definition, you can do it manually (go to Jira and change the field), or you can include the testKey within the test element.
|projectKey||The project key where the test issue will be created|
|summary||The summary for the test issue|
|description||The description of the test issue|
|testType||The test type (e.g. Manual, Cucumber, Generic)|
|requirementKeys||An array of requirement issue keys to associate with the test|
|labels||The test issue labels|
|steps||An array of test steps (for Manual tests) (link)|
|definition||The generic test definition|
|scenario||The BDD scenario|
|scenarioType||The BDD scenario type (Scenario or Scenario Outline)|
"steps" object - step definition
This object allows you to define the step fields for manual tests.
|action||The step action - native field|
|data||The step data - native field|
|result||The step expected result - native field|
"iterations" object - Data-driven test results
If you need to import data-driven test results you need to use the iterations object. Xray will store all iterations within the same Test Run object.
It is also possible to import iteration results with parameters. Currently, this is only supported for manual tests.
In this case, Xray will create a dataset automatically within the Test Run object.
|name||The iteration name|
|parameters||An array of parameters along with their values (link)|
|status||The status for the iteration (PASSED, FAILED, EXECUTING, TODO, custom statuses ...)|
"parameters" object - parameters within iteration results
|name||The parameter name|
|value||The parameter value|
"evidence" object - embedded attachments
|data||The attachment data encoded in base64|
|filename||The file name for the attachment|
|contentType||The Content-Type representation header is used to indicate the original media type of the resource|
"customFields" object - store test run custom fields
It is possible to import test run custom field values into the Test Run object. Xray will use the "id" to find the existing test run custom field in the project settings.
|id||The test run custom field ID|
|value||The test run custom field value|
Xray JSON Schema
The JSON results file must comply with the following JSON Schema:
Example 1: Importing gherkin and other test results
In this example, we are importing execution results for three existing test issues in Jira. The last issue DEMO-9 must be a BDD Test with a Gherkin definition because the results contain examples. The remaining issues can be of any test type.
Example 2: Generic Test
This is a simple example of a JSON file with execution results for a generic test.
Example 3: Importing manual test results with steps
This is a simple example of a JSON file with execution results for a manual test.
Example 4: Importing test results with Test Run Custom Fields
This is a simple example of a JSON file with execution results with Test Run Custom Fields values.
Example 5: Importing data-driven manual test results with auto-provisioning of tests
This is an example of a JSON file with a single test result.
This is a data-driven manual test with two iterations. For each iteration, we provide the parameters and the step results.
Xray will also create or update the test in Jira with the specification contained on the "testInfo" object.
Importing Multiple Execution results
Xray supports importing multiple results for the same Test issues in the same execution. These results often indicate different contexts/environments where the same Test must be executed. Xray will group all executions of the same Test in a single Test Run and present all execution information, including the different contexts in the Execution page.
When importing execution results using the Cucumber JSON output formatter, multiple executions for the same scenario/Test issue will be merged into a single Test Run.
When importing execution results using the Xray JSON format, the results JSON element must contain all execution results for the same Test Run.
Xamarin Test Cloud
If you are using the Xamarin Test Cloud for executing Cucumber mobile Tests in different combinations of mobile devices and operating systems, you can import the results to Jira by making a compressed zip file containing the multiple Cucumber JSON files.