Versions Compared

Old Version 3

changes.mady.by.user Sergio Freire

Saved on

compared with

New Version Current

changes.mady.by.user Ana Duarte

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info
titleNew Jira UI - 2025

Jira is updating the UI until summer 2025, in case you already have the new UI please check this article :  [Xray Cloud] How can I Setup Xray with the New Jira UI (2025)?

Introduction

After installing Xray, there are basically two steps you need to make at project level.

You can do it for a brand new project or for an existing project you may already have.

Table of Contents

Add Xray Issue Types to your project

you need to take a few steps at the Project level:

Table of Contents


If you're not sure where to start, you can create a Demonstration Project with sample data to explore.

Note

To enable Xray at the project level, you need to have the Browse Projects permission enabled in the Project Permission Scheme. However, some configurations - such as adding Xray Issue Types - require Jira Administration permissions. If you do not have the necessary permissions, please ask your Jira Administrator for assistance before proceeding. You can configure Xray in either a brand-new or an existing project.

All the operations described can be executed from within Xray Settings available on the Project Settings screen:

UI Steps
UI Step

On your Jira Cloud instance, enter the project you wish to configure and then click Project settings (Figure 1 - 1).

Figure 1 - ProjectImage Added

Figure 1 - Project

UI Step

Under Apps (Figure 2 - 1) click Xray Settings (Figure 2 - 2)

Figure 2 - SettingsImage Added

Figure 2 - Settings

Configuration      

Configuring Xray Issue Types in your Project

Configuring Xray Issue Types in your project ensures that Test management is seamlessly integrated and aligned with your project needs. Proper configuration allows you to easily track Tests, Requirements, and Defects, improving visibility and control over the Testing process. This setup helps teams organize testing workflows, measure coverage, and analyze results effectively.

Info

Before configuring Xray Issue types, determine whether your project is Team-managed or Company-managed, as the configuration steps differ for each project type.

Company-Managed Project (old Classic Project)

Tests, along with other entities, Tests along with other entities are abstracted as Jira Issue Types. Thus, you need to add them to the Issue Type Scheme used by your project:

UI Steps
UI Step

Access the project

...

settings as explained above (Figure 1 and 2).

UI Step

Click the Add Xray Issue Typesbutton to automatically add the available Issue Types (Figure 2 - 3).

Alternatively, you can add the Issue Types manually by clicking the Configure the Issue Type Scheme manually button (Figure 2 - 4). 

Info

Only Jira administrators can access and modify Issue Type schemes. This requirement applies to all methods of configuring Issue Types, not just the Configure Issue Type Scheme Manually option (Figure 2 - 4). If you are not a Jira administrator, you will need assistance to complete this step.

UI Step

If you chose the manual option, you will enter the Issue Types screen (Figure 3).

Click the Actions button (Figure 3 - 1) and then select Edit issue types button (Figure 3 - 2; be aware of the projects using it).

Figure 3 - ActionsImage Added

Figure 3 - Actions

UI Step

Add Test, Precondition, Test Set, Test Execution, Sub-Test Execution

...

Issue Types by dragging them from the

...

Available Issue

...

Types column (Figure 4 - 2) and dropping them on the Issue Types for Current Schemecolumn (Figure 4 - 1).

Once you're finished, click Save (Figure 4 - 3).

Figure 4 - IssuesImage Added

Figure 4 - Issues


Info
titleInfo

When a company-managed project is configured, the Testing Board may not be visible right away (Figure 5 - 1).

Figure 5 - Testing boardImage Added

Figure 5 - Testing board


If this is the case, after configuring it, simply access a page containing Xray information, such as an Xray Issue of the given project or Xray Settings of that same project, and then refresh the page.

Team-Managed Project (old Next-Gen Project)

Within team-managed projects, you first need to create the necessary Issue Types manually.

UI Steps
UI Step

On your Jira Cloud instance, enter the team-managed project you wish to configure and click Issue types (Figure 6 - 1).

Figure 6 - Issue typesImage Added

Figure 6 - Issue types

UI Step

New options will appear on the left side of the screen. There, click Add issue type (Figure 7 - 1).

A modal will open (Figure 7). Enter a name (Figure 7 - 2; mandatory field) and fill in the other fields (optional). Once you're finished, click Create (Figure 7 - 3).

You will see a confirmation message, and your Issue Type will appear right away.

Figure 7 - Issue typesImage Added

Figure 7 - Issue types


For simplicity, you can choose the same Issue Type names as the default global Xray Issue Types. Repeat these steps for all other necessary Xray entities such as Test, Precondition, Test Set, Test Plan, and Test Execution.

Info

You can download the icons for the Xray Issue Types below: 

Section
Column
width10%

Image Added

Column
width10%

Image Added

Column
width10%

Image Added

Column
width10%

Image Added

Column
width10%

Image Added


Configuring Requirements and Defects

Configuring requirements and defects in Xray enables clear visibility into project quality and progress. By linking them to Tests, you can track requirement coverage, identify unmet needs, and address defects efficiently. This setup ensures thorough Testing, effective Issue management, and improved software quality.

UI Steps
UI Step

In the Xray Settings screen (Figure 8), click Test Coverage (Figure 8 - 1).

Here, you can

Configure Requirements and Defects

...

define the Covered Issue Types (i.e., the testable entities

...

such as the

...

Typical Requirements, User Stories, Epics) by dragging the items you want from the Available Issue Types column (Figure 8 - 2) and dropping on the Covered Issue Types column (Figure 8 - 3).

Once you're done, click Save (Figure 8 - 4).

Figure 8 - CoverageImage Added

Figure 8 - Coverage

UI Step

In the Xray Settings screen (Figure 9), click Defect Mapping (Figure 9 - 1).

Here, you can

Image Removed

...

define the Covered Issue Types (i.e., the testable entities).

...

Drag the

...

items you want from the Available Issue Types column (Figure 9 - 2) to the Defect Issue Types column (Figure 9 - 3). Once you're finished, click Save (Figure 9 - 4).

Figure 9 - Defect mappingImage Added

Figure 9 - Defect mapping

Image Removed

...


Info
titleLearn more

Refer to the specific Project Settings: Test Coverage page or take a look at the extensive Global Settings if page if you want to fine-tune Xray or adapt it to your specific needs.

Enable Xray in your projects

You can enable Xray for your existing projects or create a new project with both standard and Xray issue types.

For existing projects, in the project Administration page, go to Actions at the top right-hand side. You can either:

a) set your project as a Requirements project by choosing "Enable Xray Requirement Coverage", so the requirements are covered by tests; or

b) add Xray issue types (i.e., Test, Test Set, Test Execution, Test Plan) to the project.

Image Removed

Info
titlePlease note

Since the Issue Type Scheme being used by your project may also be used by other projects, in order to add Xray's Issue Types from the project settings page you must belong to a group allowed to do so in Xray settings. The allowed groups to add Xray Issue Types can be defined in this setting.

Info
titleLearn more

If, instead, you want to quickly create a new project and use it to manage everything (e.g., requirements, defects, tests), go to the Jira Administration page for Projects. In the creation dialog, choose "Xray Test Project".

Image Removed


Expand
titleSupport/Troubleshooting

If you have questions or technical issues, please contact the Support team via the Customer Portal (Jira service management) or send us a message using the in-app chat

Info
titleLearn more

See Creating a Test Project using an Xray Template.