---
title: "Defects and Requirements"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/655360823/Defects%20and%20Requirements"
format: markdown
---
> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> > Macro (toc)

# Definition

Requirements and Defects are two concepts commonly related to Tests.

- A **Requirement** represents a singular documented physical and functional need that a particular product or process must be able to perform. It is also an important input into the verification process since a Test should trace back to a specific requirement, showing what elements and functions are necessary for the particular project. Most of the time, Requirements are the only coverable/testable entities.
- A** Defect** represents a condition in a software product that does not meet a software requirement (as stated in the requirement specifications) or end-user expectations (which may not be specified but are reasonable). It can be displayed as an error, flaw, failure, or fault in a computer program or system that produces an incorrect or unexpected result, or causes it to behave in unintended ways.

These two concepts can be mapped to different Work item Types in organizations.

Both Requirement and Defect Work item Types in your Jira instance (as well as any other Work item Type) can be configured in the [Xray Space settings](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44567037) as **coverable/testable entities**. 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. 

Defect Work item Types can also be mapped in the Xray project settings as **Defects**. With this configuration, Xray sets the default Work item Type when creating Defects from Testing, as well as providing reports specific to Defects.

> ℹ️ Both the **Test Coverage **and** Defects** can be configured for each project independently. Go to [Space Settings > Xray settings](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44567037).

# Configuration

A typical Jira configuration can have the following Work item Types configured for **Test Coverage** or mapped as **Defects **(Figure 1).

> Macro (gliffy)

Figure 1 - Work item Types


Often, a Defect Work item Type is also configured as a testable entity. To ascertain 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 Test Work item and be considered for Test Coverage charts. 

> ℹ️ The same Work item Type in a given project can be configured for **Test Coverage **and can also be a** Defect.**

  
Requirements and Defect Work items can be associated with **[Tests](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565156)** and **[Test Set](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565163)** Work items within the Jira default linking mechanism. There are specific Work item Link Types for associating these Work item Types:

- 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.

> Macro (gliffy)

Figure 2 - Work item Types

> ℹ️ **Customizing the Tests Work item Link Type: **during the installation of Xray, the Work item Link Type "Tests" that is used in the association between Tests/Test Sets and Coverable (e.g., Requirements) entities is automatically created. You can customize the default name and the outward and inward descriptions of this Work item Link Type. After making these changes, you’ll need to disable and then re-enable the add-on on the [Manage Add-ons page](https://confluence.atlassian.com/upm/viewing-installed-apps-273875714.html).
> ℹ️ 
> ℹ️ By default, the Work item link "Test" has "Tests" and "tested by" as outward and inward descriptions, respectively.
> ℹ️ 
> ℹ️ If you decide to downgrade to a version <= 3.0.x, make sure you restore the default Work item Link Type names and descriptions; otherwise, Xray will create new Work item Link Types.

## Sub-Requirements

A Requirement can be associated with Sub-requirements, resulting in a hierarchy of Requirement Work items. Epic Requirements can thus be decomposed into smaller Requirements, each associated with specific Tests. This decomposition of Requirements facilitates the management of Epic Requirements and makes their [coverage analysis](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565185) easier.

The Requirement > Sub-Requirement (i.e., parent > child) relation can be defined in the [Work item Type Mapping configuration section](https://getxraydocs.atlassian.net/wiki/pages/createpage.action?spaceKey=xraycloud&title=Project%20Settings%3A%20Test%20Coverage&linkCreation=true&fromPageId=655360823) of Xray. Sub-requirements can be associated with Requirements using the Jira linking mechanism or using Sub-task Requirement Work items.

Below (Figure 3) are the different ways Xray considers Work items as Sub-requirements of a given Requirement. 

> Macro (gliffy)

Figure 3 - Requirements


Xray also allows having more than two levels of Requirements. To achieve it you must define a custom Work item Link and use it to define the [Work items Links relations](https://getxraydocs.atlassian.net/wiki/pages/createpage.action?spaceKey=xraycloud&title=Project%20Settings%3A%20Test%20Coverage&linkCreation=true&fromPageId=655360823) between Requirements.

> Macro (gliffy)

Figure 4 - Requirements


# Operations

## Associating a Requirement with a Test

There are several ways to associate a Requirement Work item with a Test Work item. See more below.

### From the Requirement Work Item View Screen

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> In your Jira Cloud instance, open the Requirement you wish to associate a Test with. In this example, Story Work item Types are mapped as Requirements.
> 
> > Macro (rw-step)
> 
> Click the *Add* button (Figure 5 - 1) and select *Link work item* (Figure 5 - 2).
> 
> The Linked Work item section opens (Figure 6 - 1).
> 
> ![Figure 5 - Linked work item](media://627417a6-08dd-4be5-b4a0-7922b10c3a8b)
> 
> ![Figure 6 - Linked work](media://066927fd-bccc-455e-b46c-3e15a6e5d6e1)
> 
> > Macro (rw-step)
> 
> Using the middle dropdown menu from the Linked Work items section, select *is tested by* (Figure 6 - 2).
> 
> > Macro (rw-step)
> 
> Input the desired Test/Test Set Work item Key in the Work item field, or use the dropdown menu to select the Test from its Work item list (Figure 6 - 1).
> 
> > Macro (rw-step)
> 
> Once you're finished, click *Link* (Figure 6 - 4). The Work item will immediately appear in the Linked Work items section (Figure 6 - 1).

### From the Test Work Item View Screen

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> In your Jira Cloud instance, open the Test you wish to associate a Requirement with.
> 
> > Macro (rw-step)
> 
> Click the *Add* button (Figure 5 - 1) and select *Link work item* (Figure 5 - 2).
> 
> The Linked Work items section opens (Figure 7 - 1).
> 
> > Macro (rw-step)
> 
> Using the middle dropdown menu from the Linked Work items section, select* tests* (Figure 7 - 2).
> 
> ![Figure 7 - Linked work](media://7d02a3da-0335-4790-a879-ac4b69b2de08)
> 
> > Macro (rw-step)
> 
> Input the desired Requirements in the Work item field or use the dropdown menu to select a Requirement from its Work item list (Figure 7 - 3).
> 
> > Macro (rw-step)
> 
> Once you're finished, click *Link* (Figure 7 - 4). The Work item will immediately appear in the Linked Work item section (Figure 7 - 1).

### From the Test Set Work Item View Screen

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> In your Jira Cloud instance, open the Test Set you wish to associate a Requirement with.
> 
> > Macro (rw-step)
> 
> Click the *Add* button (Figure 5 - 1) and select *Link work item* (Figure 5 - 2).
> 
> The Linked Work items section opens (Figure 8 - 1).
> 
> ![Figure 8 - Linked work](media://f1b43485-9076-4771-aafe-ca484c199d2a)
> 
> > Macro (rw-step)
> 
> Input the desired Requirements in the Work item field or use the dropdown menu to select a Requirement from its Work item list (Figure 8 - 3).
> 
> > Macro (rw-step)
> 
> Once you're finished, click *Link* (Figure 8 - 4). The Work item will immediately appear in the Linked Work items section (Figure 8 - 1).

## Associating a Defect with a Test

There are two ways to associate a Defect Work item with a Test Work item.

### From the Defect Work item View Screen

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> In your Jira Cloud instance, open the Defect you wish to associate a Test with.
> 
> > Macro (rw-step)
> 
> Click the *Add* button (Figure 9 - 1) and select *Link work item* (Figure 9 - 2).
> 
> The Linked Work items section opens (Figure 10 - 1).
> 
> ![Figure 9 - Linked work item](media://95c8e518-3af4-4983-80a0-03535cc4cb62)
> 
> > Macro (rw-step)
> 
> Using the middle dropdown menu from the Linked work items section, select* is tested by* or *is created by* (Figure 10 - 1).
> 
> ![Figure 10 - Linked work](media://7c98af15-97c3-4d97-8e45-50a10f004384)
> 
> > Macro (rw-step)
> 
> Input the desired Test Work item Key in the Work item field or use the dropdown menu to select Tests from its Work item list (Figure 10 - 3).
> 
> > Macro (rw-step)
> 
> Once you're finished, click *Link* (Figure 10 - 4). The Work item will immediately appear in the Linked Work items section (Figure 10 - 1).

### From the Test Work Item View Screen

> Macro (rw-ui-steps-macro)
> 
> > Macro (rw-step)
> 
> In your Jira Cloud instance, open the Test you wish to associate a Defect with.
> 
> > Macro (rw-step)
> 
> Click the *Add* button (Figure 11 - 1) and select *Link work item* (Figure 11 - 2).
> 
> The Linked Work items section opens (Figure 12 - 1).
> 
> ![Figure 11 - Linked work item](media://e5409472-e846-470a-aabe-ad11e51efa19)
> 
> > Macro (rw-step)
> 
> ![Figure 12 - Linked work](media://c75a3d41-8639-4315-9dd6-66d93448f211)
> 
> > Macro (rw-step)
> 
> Using the middle dropdown menu from the Linked Work items section, select* tests* or *created* (Figure 12 - 2).
> 
> > Macro (rw-step)
> 
> Input the desired Defects in the Work item field or use the dropdown menu to select a Defect from its Work item list (Figure 12 - 3).
> 
> > Macro (rw-step)
> 
> Once you're finished, click *Link* (Figure 12 - 4). The Work item will immediately appear in the Linked Work items section (Figure 12 - 1).


<details>
<summary>Support/Troubleshooting</summary>

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).
</details>