Xray Integration

In this page

What is Xray?

(supported since Better Excel Exporter 4.6.0)

Xray is a complete, end-to-end test management app for Jira. It supports the entire testing and quality assurance lifecycle: test planning, test design, test execution and test reporting.

Xray integration features

• You can export tests and their steps with the following details: Test Type, Test Status, Test Steps, Preconditions associated with a Test, Test Sets associated with a Test, Test Plans associated with a Test and Test Repository Path.
• You can export the test runs for detailed test reports. The following details are exported for each run: Test Execution Key, Test Run Fix Versions, Test Run Test Environments, Test Run Assignee, Test Run Executed By, Test Run Started On, Test Run Finished On, Test Run Defects, Test Run Comment, Test Run Evidences, Test Run Status, Test Step Index, Test Step, Test Step Data, Test Step Expected Result, Test Step Actual Result, Test Step Attachments, Test Step Defects, Test Step Comment, Test Step Evidences and Test Step Status.
• You can export preconditions with the following details: Precondition Type, Precondition Definition, Test Repository Path, Test Count and Tests associated with a Precondition.
• You can export test sets with the following details: Test Count, Tests associated with a Test Set and Test Set Status.
• You can export test plans with the following details: Test Count, Tests associated with a Test Plan, Test Plan Status and Test Executions associated with a Test Plan.
• You can export test executions with the following details: Test Environments, Test Plans, Test Count, Tests associated with a Test Execution, Test Execution Status and Test Execution Defects.
• You can export coverable issues with the following details: Test Coverage Status, Test Count and Tests associated with a coverable issue.
• Better Excel Exporter also offers two report templates: one focusing on tests and their relations (with test sets, test plans, test executions), while the other focusing on test runs and test results. Both include several pivot tables and pivot charts, which are super-useful as they are, but can also be used as a starting point to create custom Excel reports from Xray data.

(Need more features? Tell us in a support ticket!)

Xray integration vs. the Xray built-in Excel exports

You may want to ask: if Xray has a built-in Excel export feature, why would you use another app for the same?

While the Xray built-in Excel exports may be sufficient for basic use cases, the Better Excel Exporter integration is more powerful in, at least, these:

• It is extremely customizable.
  Instead of accepting the pre-defined export types in Xray, you can define your own types via Excel templates.
• It supports all the powerful Excel features.
  You can use Excel formulas and functions, custom calculations in Groovy (sorting, complex math, data integration, etc.), charts, pivot tables, pivot charts, Visual Basic macros, among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Xray data and other apps' data in the same Excel file.
• It comes with powerful templates optimized for Xray.
  You can use those "as is", or customize them to your needs.
• It is well-documented with the customization guide, the Expression Reference Manual, the recipes, and such.

If at least one of these is important for you, give the app a try.

Configuration

Configuring the Xray GraphQL API access

As this integration relies on the Xray GraphQL API, you need to configure the credentials for the GraphQL API calls in xray-tool.groovy:

1. In Jira, click the cog icon "⚙" in the top right → Apps → Xray → API Keys.
2. Click Create API Key.
3. Search for and select your user account.
4. Click Generate.
5. Copy the Client Id from the panel (using the copy-page icon).
6. Open a new tab and login to your Jira.
7. Click the cog icon "⚙" in the top right → Apps → Better Excel Exporter → Excel templates.
8. Open the xray-tool.groovy file for editing and paste the key to the value of the xrayClientId variable (don't remove the quotation marks around the string!):

   // xray-tool.groovy
   
   /* Xray Cloud GraphQL API authentication */
   def xrayClientId = '243808F14838914481A1862140BF6382') // Xray Client ID, see: https://www.midori-global.com/products/better-excel-exporter-for-jira/cloud/documentation/integrations/xray
   def xrayClientSecret = '08009e082d54e2155cc95bbfccfb75206e5027c28991ad31ce517edd6250c204')
   

9. Switch back to the other tab, copy the Client Secret, and paste it to the value of xrayClientSecret.
10. Save the changes in xray-tool.groovy. (Don't worry about storing keys here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)

Configuring the coverable issue types

You can configure what issue types are considered as coverable by the following variable in the xray-tool.groovy template:

def static coverableIssueTypeNames = ['Story', 'Task']

Configuring the export format for the associated Xray-managed issues

Xray is using several tabs that associate an Xray-managed issue type with another, e.g. Preconditions, Test Sets, Test Plans, etc.. In the Xray web interface, these issues are displayed in a customizable column configuration but the Xray GraphQL API only returns issue IDs.

When exporting to Excel, Better Excel Exporter resolves the issue IDs to issue keys and summaries, and expands the values to the longer, but externally usable format "[FOO-123] My first test, [FOO-456] My second test". If you want to turn this off and return to "FOO-123, FOO-456", set this configuration variable to false in the top of the xray-tool.groovy script:

def xrayIssuesWithSummaries = true

These values are comma-separated by default. If you want to break them to new lines within the cell, to make it easier to read at the cost of the increased cell height, it is simple. Just change the join() method's argument from ", " to "\n" in the xray-tool.groovy script in the following way:

def getAssociatedIssues(list) {
	if (xrayIssuesWithSummaries) {
		list ? list.results.collect {
			def issue =  getIssueById(it.issueId)
			"[${issue.key}] ${issue.summary}"
		}.join("\n") : null
	} else {
		list ? list.results.collect { getIssueById(it.issueId).key }.join("\n") : null
	}
}

Troubleshooting

Only the first 100 associated items are exported

For example, when you export a test plan with more than 100 associated tests, only the first 100 tests will be exported. This is due to a technical limitation at the moment. The Xray GraphQL API uses a limit parameter with a maximum value of 100 for the queried nodes. To get more, paging should be used, but that's supported only on the "root level" (i.e. for the exported Xray entity).

For test sets, only the first 30 tests and their 30 test runs are exported

The Xray GraphQL API does not allow requesting more than 10,000 total items in a single API call. To obey that rule, lower values are used in case of test set queries.

The exported test status does not match the status displayed in the UI

Xray provides different configuration options in the web interface to calculate the status of the tests (e.g. limiting to specific environment, giving precedence of final statuses over non-final statuses). However, we cannot access this configuration during the export, therefore it's always the latest and final status that's exported.

Test runs of parameterized tests are not exported

The export of parameterized tests' test runs is not supported currently.

Learn more about Xray

• Xray product information (at its own vendor)
• Xray documentation
• Xray app page (on the Atlassian Marketplace)