---
title: "Quick Setup"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44565860/Quick%20Setup"
format: markdown
---
> ℹ️ ### New Jira UI - 2025
> ℹ️
> ℹ️ [Jira was updating the UI in 2025](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/520552451). 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)?](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/130449409)
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> > Macro (toc)
# Introduction
There are [two separate Xray apps](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/392921546):
- **[Xray for Jira Test Management](https://www.getxray.app/test-management?utm_source=adwords&utm_medium=cpc&utm_campaign=gg_search_bofu_xray_brand_europe&utm_term=xray%20test%20management&hsa_acc=9970092548&hsa_cam=21151579322&hsa_grp=179131227587&hsa_ad=742407804447&hsa_net=adwords&hsa_src=g&hsa_mt=e&hsa_kw=xray%20test%20management&hsa_tgt=kwd-488738308063&hsa_ver=3&gad_source=1&gad_campaignid=21151579322&gbraid=0AAAAACfrmty9ifZJ63zdRhjHC_tZnaHSM&gclid=CjwKCAjwkvbEBhApEiwAKUz6-5KVPUyEmAuIEJQMsiGYxe8xcN5GC1hHLA9kXxSF6S9V_zAIxpvU9BoCbBAQAvD_BwE)**: the core Test management solution for smaller teams.
- **[Xray Enterprise](https://www.getxray.app/xray-enterprise)**: a solution with advanced capabilities tailored for large-scale enterprises.
After [installing](https://docs.getxray.app/space/XRAYCLOUD/44566344) Xray, you need to take a few steps at the [Space level](https://docs.getxray.app/space/XRAYCLOUD/44567037) to ensure the core benefits of the tool can be delivered. There are two major parts - adding Xray Work items and configuring Coverable items & Defects.
> ⚠️ To enable Xray at the Space level or to change the configuration, you need to have the *Administer Spaces* permission enabled in the [Space Permission Scheme](https://support.atlassian.com/jira-cloud-administration/docs/space-access-and-configuration-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 Space.
> ℹ️ If you're not sure where to start, you can create a [Demonstration Project](https://docs.getxray.app/space/XRAYCLOUD/44565799) with sample data to explore.
> ℹ️
> ℹ️ You can also check the interactive version of this tutorial - [Quick Setup](https://xray.navattic.com/ql2o07vs).
# Concepts and Configurations
## Xray Work Item Types
Most Xray entities (except [Test Runs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565109) and [Test Repository](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565166)) are native Jira Work items. Proper configuration of your Space ensures that Test management is seamlessly integrated and aligned with your Space needs. It allows you to easily track [Tests](https://docs.getxray.app/space/XRAYCLOUD/44565156), improving visibility and control over the QA process.
> ℹ️ - Before configuring Xray Work item types, determine whether your Space is [Team-managed or Company-managed](https://support.atlassian.com/jira-software-cloud/docs/what-are-team-managed-and-company-managed-projects/), as the configuration steps differ for each Space type. Then, consider your [Space Organization](https://docs.getxray.app/space/XRAYCLOUD/44566397/Project+Organization) options.
> ℹ️ - Issue Types is the old Jira UI terminology; Work item Types is the new terminology. Go [here](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/520552451) to learn more.
> Macro (rw-ui-steps-macro)
>
> ### Xray Work Item Types on a Company-Managed Space
>
> > Macro (rw-step)
>
> On your Jira Cloud instance, enter the Space you want to work on. Click the ellipsis button (Figure 1 - 1) and then *Space settings* (Figure 1 - 2).
>
> 
>
> > Macro (rw-step)
>
> On the Space settings screen (Figure 2), click *Apps* (Figure 2 - 1) and then *Xray settings* (Figure 2 - 2).
>
> 
>
> > Macro (rw-step)
>
> On the Xray Settings screen (Figure 3), click the *Add Xray Issue Types* button to add the available Issue types automatically.
>
> Alternatively, you can add the Issue Types manually by clicking the *Configure the Issue Type Scheme manually* button (Figure 3 - 2).
>
> 
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> 1 - You will enter the Work items -> Types screen (Figure 4).
>
> 
>
> 2 - Click the *Actions* button (Figure 4 - 1) and then select the *Edit work types* button (Figure 4 - 2; be aware of all the Spaces using this scheme).
>
> 3 - Add Test, [Precondition](https://docs.getxray.app/space/XRAYCLOUD/44565159), [Test Set](https://docs.getxray.app/space/XRAYCLOUD/44565163), [Test Plan](https://docs.getxray.app/space/XRAYCLOUD/44565153/Test+Plan), [Test Execution](https://docs.getxray.app/space/XRAYCLOUD/44565117), [Sub-Test Execution](https://docs.getxray.app/space/XRAYCLOUD/44565114) Work item Types by dragging them from the Available Issue Types column (Figure 5 - 1) and dropping them on the Issue Types for Current Scheme column (Figure 5 - 2).
>
> Once you're finished, click *Save* (Figure 5 - 3).
>
> 
### Xray Work Item Types on a Team-Managed Space
Within team-managed Spaces, you must first manually create the necessary Issue Types.
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> On your Jira Cloud instance, enter the Space you want to work on. Click the ellipsis button (Figure 6 - 1) and then *Space settings* (Figure 6 - 2).
>
> 
>
> > Macro (rw-step)
>
> New options will appear on the left side of the screen. There, click *Work type*s (Figure 7 - 1) and then *Add work type* (Figure 7 - 2).
>
> 
>
> > Macro (rw-step)
>
> A modal will open (Figure 8).
>
> There, enter a name (Figure 8 - 1; mandatory field), fill in the description (Figure 7 - 2; optional), and provide the Xray-specific icon (Figure 8 - 3; recommended, you can download them below).
>
> Once you're finished, click *Create* (Figure 8 - 4).
>
> 
>
> > Macro (rw-step)
>
> You will see a confirmation message, and your Work Type will appear right away.
>
> > ℹ️ For simplicity, you can choose the same Work Type names as the default global Xray Work Types. Repeat these steps for all other necessary Xray entities such as **Test, Precondition, Test Set, Test Plan, Test Execution, **and** Sub-Test Execution**.
>
> **Icons Download**
>
> | | | |
> | --- | --- | --- |
> |  |  |  |
> |  |  |  |
## Coverable Items and Defects - Mapping
> ℹ️ Throughout the documentation, you can see us using *Coverable* and *Requirement* interchangeably. For the avoidance of doubt, we do not refer to any specific “Requirement” Work item type - we mean “Requirement” as an abstract category of items that specify Product needs (but, of course, you can also create a Work item called “Requirement” and map it as Coverable in Xray).
Configuring Coverable items and Defects in Xray enables clear visibility into Space quality and progress. By linking those entities to Tests, you can track Requirement coverage, identify unmet needs, and address defects efficiently. This setup ensures thorough Testing, effective Work items management, and improved software quality.
Let’s start with the definitions specific to our setup purposes:
- A **Coverable entity** is a Jira Work item that you can cover with Tests to validate its acceptance criteria.
- A **Defect** is a Jira Work item that represents an error, flaw, failure, or fault in the System Under Test that produces an incorrect or unexpected result.
Xray **does not create** any special Work types for these “roles”. Instead, you can **map** these two concepts to different Work item Types that are already available in your Jira Spaces.
### Coverable Work Items
Both the Coverable entities and Defects can be configured for each Space independently.
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Let’s start with Coverables by going to *[Space Settings](https://docs.getxray.app/space/XRAYCLOUD/44567037)*[ > ](https://docs.getxray.app/space/XRAYCLOUD/44567037)*[Xray settings](https://docs.getxray.app/space/XRAYCLOUD/44567037)* (Figure 2). There, select *[Test Coverage](https://docs.getxray.app/space/XRAYCLOUD/44566845/Project+Settings:+Test+Coverage)* (Figure 9).
>
> 
>
> > Macro (rw-step)
>
> To designate the Work items you want as Coverable, drag them from *Available Issue Types* (Figure 9 - 1) to *Coverable Issue Types* (Figure 8-2). In this example, “Task”, “Story”, “Epic”, and “Requirement” can be covered with Tests.
>
> > Macro (rw-step)
>
> Scroll to the end of the screen and click *Save* (Figure 10 - 3).
>
> 
>
> > ✅ When a Work item Type is configured to be coverable/testable, Xray provides specific web panels and reports to display the coverage of Work item as well as their latest status regarding Testing (you will see examples below).
### Hierarchy of Coverable Work Items
Below the *Available Issue Types* (Figure 9 - 1) and *Coverable Issue Types* (Figure 9 - 2) columns, you can see the *Test Coverage Hierarchy* section (Figure 10). This section enables Xray to respect the hierarchical relationships between different Work items you’ve selected as Coverable (if applicable).
- The first two checkboxes (Figure 10 - 1) allow Xray to consider the “implicit” dependencies that Jira establishes between Epics and children or Work items and their sub-tasks.
- The dropdown and the radio buttons (Figure 10 - 2) allow Xray to consider **custom relationships** using the Jira links that you define and their direction. This unlocks the hierarchy with more than two levels (as long as the link type is the same between the levels).
For example, you are doing fairly granular risk-based Testing and your overall structure is something like Epics → Stories → Risks-> Mitigations (with Risks linked to Stories via *Verifies* relationship and Mitigations linked to Risks via the same “Verifies” relationship). So, you would like Xray to account for that relationship - you select *Verifies* from the dropdown (Figure 10 - 2). Then, elements like [Requirement Traceability Report](https://docs.getxray.app/space/XRAYCLOUD/44565208/Requirement+Traceability+Report) will properly reflect the hierarchy and allow you to drill down (Figure 11).
### Defects
Similar principles apply to designating Work items as [Defects](https://docs.getxray.app/space/XRAYCLOUD/44568504/Project+Settings:+Defect+Mapping) (without the hierarchy part).
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> From *[Space Settings](https://docs.getxray.app/space/XRAYCLOUD/44567037)*[ > ](https://docs.getxray.app/space/XRAYCLOUD/44567037)*[Xray Settings](https://docs.getxray.app/space/XRAYCLOUD/44567037)* (Figure 2), select *Defect Mapping* (Figure 12 - 4).
>
> 
>
> > Macro (rw-step)
>
> To designate the Work items you want as Coverable, drag them from the *Available Issue Types* column (Figure 12 - 1) to the *Coverable Issue Types column* (Figure 12 - 2). In this example (Figure 12), only the *Bug* Work item is selected.
>
> > Macro (rw-step)
>
> Scroll to the end of the screen and click *Save* (Figure 12 - 3).
>
> > ℹ️ Sometimes, a Defect Work item Type is also configured as a testable entity. To make sure that a Defect does not occur again, it can be considered for Testing. **Xray allows the same Work item Type to be mapped as being Coverable and as a Defect.** A Defect can then be associated with a Test Work item and be considered for Test Coverage charts.
>
> > Macro (rw-step)
>
> Once a Space is configured (Figure 13 - 1), confirm the Testing Board presence by navigating to the Space board (Figure 13 - 1), opening the *More* menu (Figure 13 - 2), and clicking *Testing Board* (Figure 12-3).
>
> 
>
> > ℹ️ - If this is not visible, try accessing a page containing Xray information, such as an Xray Work item of the given Space or Xray *Settings* in that Space again, and then refresh the page.
> > ℹ️ - Refer to the specific *[Space Settings](https://docs.getxray.app/space/XRAYCLOUD/44567037)* page or take a look at the extensive *[Global Settings](https://docs.getxray.app/space/XRAYCLOUD/44565853)* page if you want to fine-tune Xray or adapt it to your specific needs.
## Work Item Relationships
Requirements and Defect Work items can be associated with **[Test](https://docs.getxray.app/space/XRAYCLOUD/44565156)** and **[Test Set](https://docs.getxray.app/space/XRAYCLOUD/44565163)** Work items within the Jira default linking mechanism. There are specific Work item Link Types for associating these Work item Types (Figure 14):
- Requirement R **"is tested by"** test T (or Test Set TS).
- Test T (or Test Set TS) **"tests"** requirement R.
- Defect D **"is created by"** Test T.
- Defect D "**is tested by**" Test T (or Test Set TS).
- Test T "**created**" defect D
- Test T (or Test Set TS) "**tests**" defect D.
### Customizing the Tests Work Item Link Type
During the [installation of Xray](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44566344), the Work item Link Type "Tests" that is used in the association between Tests/Test Sets and Coverable entities is automatically created. You can customize the default name and the outward and inward descriptions of this Work item Link Type as described in [this article](https://docs.getxray.app/space/ProductKB/141656082/[Xray]+How+to+properly+change+Xray's+%22Tests%22+Link+Type+Name).
However, the Default Installed Xray's Link Type **should never be deleted**. Deleting it will cause the Test Coverage to not work. Manually re-adding the Link Type with the same Name/description will not fix the error: **you would have to reinstall Xray**. We also don't recommend changing the Name of the link unless you have a strong reason to.
## Basic Operations
### Associating a Coverable Item with a Test
There are several ways to associate a Coverable Work item with a Test Work item. In this page, we will describe two of the most popular.
#### From the Coverable Work Item View Screen
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> In your Jira Cloud instance, open any Work item you’ve selected as Coverable in the previous section. In this example, it’s working with Story Work item Types.
>
> Make sure the Xray Test Coverage panel is enabled and visible (Figure 15 - 1).
>
> 
>
> > Macro (rw-step)
>
> Click the *Add Tests* button (Figure 15 - 2). Select whether you want to create a new one, add existing ones individually or via a Test Set, or ask AI to help with creation (Figure 16).
>
> 
>
> > Macro (rw-step)
>
> Regardless of the option you choose, once you are finished with the subsequent dialogs, you will see the Tests in the Test Coverage section as well as in the Linked Work items one (Figure 17).
>
> 
#### From the Test Work Item View Screen
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> In your Jira Cloud instance, open any Xray Test Work item.
>
> Select *Add linked work item *(Figure 18 - 1). If that section is not visible, click the *+* button (Figure 18 - 2) and select *Link work item*.
>
> 
>
> > Macro (rw-step)
>
> Select *Tests* in the link type (Figure 19 - 1) and provide one or multiple keys for Coverable items, then click *Link* (Figure 19 - 1).
>
> The result will be similar to Figure 17 (with one Test item showing in the Test Coverage panel of the target Coverable item).
>
> 
### Associating a Defect with a Test
There are also several ways to associate a Defect Work item with a Test Work item. In this page we will describe two of the most popular:
- Defect Work items do not have “special” Xray panels. This means that you can create a link between a Defect and a Test in the same way described in the section above (via the *Linked work items* section, but selecting the “created”/”is created by” type).
- Creating or associating Defects at the Test Run level is often recommended, as it provides richer context. For example, when a Defect is created at the Step level, the step details are automatically included in the Defect description. This option is available from the Test Run Details view (Figure 20).
> ℹ️ To learn more before finishing the *Getting Started* documentation section, you can check the [Test Runs article](https://docs.getxray.app/space/XRAYCLOUD/44565109/Test+Runs).
Support/Troubleshooting
If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577312).