In this page

What is Xray?

(supported since Better PDF 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 Xray-managed information using the highly-configurable sections in the issue-fo.vm template:
    • for tests:
      • for manual tests: test type, test steps (instructions, input/data and expected result), test repository path, test status, pre-condition list, test set list, test plan list and test run list
      • for Cucumber tests: test type, scenario, test repository path, test status, precondition list, test set list, test plan list and test run list
      • for generic tests: test type, definition, test repository path, test status, precondition list, test set list, test plan list and test run list
    • for preconditions: precondition type, definition, test repository path and test list
    • for test sets: overall execution status and test list
    • for test plans: overall execution status, test list and test execution list
    • for test executions: test plans, test environments, overall execution status and test list
    • for coverable issues: test coverage status and test list

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

Xray integration vs. the Xray built-in PDF exports

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

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

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 the issue-fo.vm template:

  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 log in to your Jira.
  7. Click the cog icon "⚙" in the top right → Apps → Better PDF Exporter → PDF templates.
  8. Open the issue-fo.vm template for editing and paste the key to the value of the $xrayClientId variable (don't remove the quotation marks around the string!): 
    #set($xrayClientId = '243808F14838914481A1862140BF6382')
#set($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 issue-fo.vm. (Don't worry about storing keys here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)

Configuring the Xray sections in PDF templates

The template issue-fo.vm contains the following configuration parameter in its top part: 

#set($exportXrayIssueDetails = $pdfView.name.contains('Detailed')) ## set to "true" to export Xray issues with their details

As you see, the template checks if the view name contains the word "Detailed", and displays more details of the Xray entities accordingly. If the export is made with the default Xray views (like "Xray (Detailed)"), this will work as expected. But, nothing prevents you from enforcing it to true or false like this: 

#set($exportXrayIssueDetails = true)

Note that the issue-fo.vm template shows the Xray-specific sections only for the issues that are actual Xray entities. It decides whether an issue is an Xray entity by checking its issue type name (e.g. if it is a "Test Plan"). Therefore, if you rename issue types, you also need to adapt the logic around this part in the template code: 

## Xray
#set($xrayIssueTypes = ["Precondition", "Test Plan", "Test Set", "Test Execution", "Sub Test Execution", "Xray Test"])
#if($xray && ($xrayIssueTypes.contains($issue.issueTypeObject.name) || ($issue.issueTypeObject.name == "Test" && $issue.issueTypeObject.description.contains("Xray")) || $coverableIssueTypeNames.contains($issue.issueTypeObject.name)))
	## ...

Additionally, you need to make adjustments in the xray-tool.groovy script as well.

Configuring the coverable issue types

You can configure what issue types are considered as coverable by the following variable in the issue-fo.vm template: 

#set($coverableIssueTypes = ['Story', 'Task']) ## comma separated list of the coverable issue types

It needs to be aligned with the project-level Xray settings.

Configuring the export format for the "Overall Execution Status" field

When you have 4 tests and all those were executed successfully (e.g. in a test execution), the status overview field will be exported in the "full" format that includes all statuses (even those with zero test counts): 

PASSED: 4 (100%), FAILED: 0 (0%), EXECUTING: 0 (0%), TODO: 0 (0%)

For the easier reading, you may want to use the compact format that shows only the non-zero statuses: 

PASSED: 4 (100%)

You can switch to the compact format by setting this configuration variable to false in the issue-fo.vm template: 

#set($exportZeroStatuses = false)

Additionally, you can also hide the percentage values (and show the counters only) like: 

PASSED: 4, FAILED: 0, EXECUTING: 0, TODO: 0

For that, set the following configuration variable to false: 

#set($exportStatusPercentage = false)

Configuring the export format for the Xray manual tests' test steps

In the web user interface, Xray displays the test steps for manual tests as a table. When exporting to PDF, Better PDF Exporter can either export the test steps as a table or as blocks. The output format is controlled by the following variable in the issue-fo.vm template: 

#set($exportManualTestStepsAsTable = true) ## set to "true" to export "Manual Test Steps" as table

This table helps to choose the one that is more suitable for your exports:

$exportManualTestStepsAsTable Format in the PDF document
true Table with "Action", "Data" and "Expected Result" columns and an extra "Attachments" row.

Tip: choose this for most use cases. (This format is more human-readable.)
false Step number, "Data", "Expected Result" and "Attachments" are exported to separate lines, with an empty line between steps.

Tip: choose this if the space in the paper is limited. (This format is using less paper space.)

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