Xray

1. Introduction

Ketryx provides seamless integration with Xray Test Management for Jira by fetching data from Xray and mapping it to Ketryx items.

This guide explains how to set up the Xray for Jira integration, describes how data is mapped to Ketryx by default, and outlines how it can be customized.

2. Setting up the Xray integration

Setting up the Xray integration will require ..

• .. Jira Ketryx app is installed, and a Jira connection is set up in Ketryx (see Jira | 2.

  Setting up the integration), and

• .. the Manage connections permission within Ketryx.

To fetch data from Xray, Ketryx needs an Xray API key. The following steps need to be completed:

1. Create an Xray API key in Xray

2. Provide the Xray API key in Ketryx

3. Review how Xray is now connected with your Ketryx projects

2.1 Create an Xray API key in Xray

In Jira, navigate to Apps > Manage your apps > XRAY > API Keys, and select "Create API Key." You will need the Client Id and Client Secret for the next step.

2.2 Provide the Xray API key in Ketryx

In Ketryx, navigate to Organization > Connections, locate the Xray section, set the Client ID and Client Secret, and then save.

2.3 Review how Xray is now connected with your Ketryx projects

The Jira Xray app is linked to your Jira instance and is now also connected to Ketryx. Any Ketryx Project (existing or new) that is connected to a Jira space (former project), which is using Xray issue types, will now sync Xray data based on the default or custom mapping (see next section "Mapping Xray data with Ketryx items").

Example:

1. Locate or create a Jira project that is connected to a Jira project (further information about the Jira integration can be found in the Jira integration documentation)

2. Create an Xray Test in the Jira project

1. Navigate to the Ketryx All items page and synchronize the project

2. Review that the Xray Test Case is now synced with Ketryx, including the Xray data associated with it, such as Steps

Note that, when you open an Xray item, such as a Test Case in Ketryx, you will observe that the item is not editable (there is no 'Edit' button). If you need to edit it, click the Source tab to open and edit the item in Jira.

3. Mapping Xray data with Ketryx items

By default, Xray issue types Test Plan, Test, and Text Execution are synced with Ketryx. The mapping can be customized.

3.1 Default & custom data mapping to Ketryx

• Xray Test Plans are associated with a particular version using Jira's Fix versions field (or another version field in a custom configuration)

• Xray Test Plans contain Xray Test Executions or Xray Tests

• Xray Test Executions contain one or more test runs, where each test run executes a particular Xray Test

• Xray Tests can be associated with their tested items through Jira's native tests link

For Xray Tests, Test Executions, and Test Plans, when the types in Jira use the names "Test", "Test Execution", "Test Plan", "Xray Test", "Xray Test Execution", or "Xray Test Plan", these item types will map to Ketryx items by default - Issue mapping in the Ketryx Advanced Settings is not needed. When other type names are used for these items, it is necessary to use Issue mapping in the Ketryx Advanced Settings to read the items into Ketryx. It is always necessary to use Issue mapping for other Xray item types, such as Precondition and Test Set, to read them into Ketryx.

If your Jira is configured with Xray work item types prior to connecting Ketryx, the Ketryx-specific work types may be created with deconflicted names, such as Ketryx Test Execution instead of the usual Test Execution work item type.

The following setup must be performed by a Jira user with Jira Admin access.

Please note, that when using the default Ketryx scheme, you need to make a copy of that schema in Jira and add Xray items to it. Then apply the new scheme to the Jira project in order to make Xray items available. Establishing a Xray connection does not automatically change work type schemes.

4. Using Xray Test Plans

Note that, within the project setting (Configurations | Settings | Test management), besides other Test management configurations, you can set "Automatically update release test plan based on external test plan(s)," which automates the following steps.

With Xray, you will usually maintain one or more Xray Test Plans in Jira and associate them with a version. To replicate the same selection of executed tests in the release test plan in Ketryx, do the following on the Test management page:

1. Select the relevant version to be released

2. Activate the filter Not contained in Xray test plan

3. Select all filtered tests by clicking the checkbox in the top-left corner of the table

4. Exclude the selected tests by choosing Manage release test plan > Exclude selected items

5. Confirm the exclusion and approve the test plan

5. Frequently Asked Questions

5.1 What are the current limitations of the X-ray integration?

5.1.1 Linking Xray tests to requirements and specifications

Important limitation: The traceability widget cannot be used to link Xray test items to Ketryx requirements, specifications, or test executions.

When working with Xray tests, you must use Jira's built-in linking functionality (the "tests" link type) to connect Xray tests to requirements, specifications, or test executions in Jira.

Why this limitation exists: Xray Tests are non-editable items from Ketryx's perspective, managed entirely within the Xray system. The traceability widget can only modify items that are fully managed by Ketryx or standard Jira items.

For more details on Xray item linking behavior, see the support article on Xray item relationships.

5.2. How are Xray Tests, Test Plans, and Test Executions represented in the Traceability Widget?

From an Xray Test perspective, the Traceability Widget shows the relationship to the Xray Test Plan as Contain in relations and the relationship to the execution of a Test Plan as Executed by relation.

A Test Execution either represents the execution of the full Test Plan or an ad hoc execution of one Test Case.

Note that Ketryx will always use the latest Test Execution for each Test Case, regardless of whether it was created for every Test Case in the Test Plan or just for an individual Test Case.

5.2.1 Test Execution with a Test Plan

If a Test Plan contains multiple Test Cases, the Test Execution will also contain these Test Cases and can be perceived in the Traceability Matrix as "* related items hidden" | "Showing * related item(s)". Additionally, all Test Executions would also be shown as such.

Example: The Text Plan "Xray Test Plan 1" includes the two test cases "Xray Test 1" and "Xray Test 2". The Test Plan "Xray Test Plan 1" has been executed with "New Execution for Test Plan Xray Test Plan 1":

The Test Execution will contain the results of each test case run:

5.2.2 Ad hoc Test Execution of a Test Case

If a Test Case is executed ad hoc, the Test Case is related as Executed by to the Test Execution.

5.3 The Ketryx widgets are not displayed on the Xray Test Plan, Test, or Test Execution?

Ketryx widgets might not be displayed by default when Xray items are displayed in Jira.

You can either open the app on the Jira item using the View app actions button or configure the default behaviour using the Ketryx advanced setting "Jira widget display" (see Advanced Setting | Jira widget display)