Introduction
To use this report, you must enable Requirement Coverage for your project.
The Xray Requirement Traceability report shows the Requirements traceability through Tests, Test Runs, and Defects.
This report enables you to follow the life of a Requirement in both forward and backward directions (i.e., from its origin all the way through Tests, Test Runs, and Defects). It facilitates the analysis of the overall Requirements coverage status.
Possible usage scenarios:
- Make full traceability analysis, from Requirements <=> Tests <=> Test Runs <=> Defects.
- Evaluate the Requirement status for a given version and see all linked (open/closed) Defects.
- See the Tests and Test Runs that cover each Requirement, and analyze how that contributes to the overall Requirement status.
- Analyze the Requirements and related Executions and Defects in a given Test Environment.
- See what Defects are impacting the Requirements or a subset of the Requirements of a specific version.
Operations
Report Access and Usage
With the Requirement Coverage Already Enabled
On the top menu of your Jira Data Center instance, click Projects and select a project (Figure 1 - 2).
Figure 1 - Access
A menu will open on the left side of the screen. There, click Reports (Figure 1 - 3). Several options will appear on the screen (Figure 2). Scroll down and click the Requirement Traceability Report (Figure 2 - 1).
Figure 2 - Access
The Requirement Traceability screen will open (Figure 3).
Select the Scope, Version, and Environment (Figure 3 - 1) and apply filters, if you want (Figure 3 - 2).
Figure 3 - Report
Click Generate Report (Figure 3 - 3).
The report will appear immediately (Figure 4 - 4).
Figure 4 - Report
Without the Requirement Coverage Enabled
If you are working on a Project that doesn't have the Requirement Coverage enabled, and try to access the Requirement Traceability report, you will see a warning (Figure 5 - 1).
To be able to access/generate a Requirement Traceability report, you have to enable the Requirement Coverage for that project first.
Figure 5 - Disabled
Reading the Report
At the top of the Requirement Traceability report, you'll find three areas related to the report and the data shown there:
- Figure 4 - 1: analysis and scope, for choosing how to analyze the entities.
- Figure 4 - 2: filter, for selecting the source data.
- Figure 4 - 3: quick filter based on calculated coverage for the defined scope on Figure 4 - 1.
- Figure 4 - 4: main report areas.
- Figure 4 - 5: report visualization information and options.
Source Data
Source Requirements Issues can be directly provided (Figure 4 - 2) using the Requirement fields configured in the Basic tab (Figure 6 - 1) or the JQL written in the Advanced tab (Figure 6 - 2).
Xray Enterprise Feature
Cross-project reports is an Xray Enterprise feature. If you do not have Xray Enterprise installed, the project filter is not available, and this report can only be generated with a single project.
If you have Xray Enterprise, it is mandatory to select at least one project before generating the report.
Figure 6 - Fields
By default, the Basic tab (Figure 6 - 1) provides the following fields:
- Fix Version (Figure 6 - 3): version assigned to Requirements.
- Sprint (Figure 6 - 6): sprint assigned to Requirements (only available if Jira Software is installed).
- Component (Figure 6 - 4): components assigned to Requirements.
- Status (Figure 6 - 7): the Issue's workflow status.
- Resolution (Figure 6 - 5): the Issue's workflow resolution.
- Contains text (Figure 6 - 8): filter requirements by text.
By clicking More (Figure 6 - 9), it's possible to select which fields will be used to filter the Requirements (Figure 7 - 1):
- Selecting fields will enable further filtering of the Requirements.
- Unselecting fields will remove them from the dialog and thus from the search criteria.
Figure 7 - More
The default fields cannot be removed from the dialog.
Alternatively, to the Basic tab (Figure 6 - 1), the Advanced tab (Figure 6 - 2) offers the possibility of filtering the requirements via JQL (Figure 8 - 1):
Figure 8 - Advanced
If you wish, you can clear the filter to see all Requirements once again: click the Clear button (Figure 6 - 10) and then press Apply (Figure 6 - 9).
Quick Filters
In the Quick Filters section (Figure 9 - 1), you can filter out Requirements based on their current coverage status for the scope defined. By default, all possible coverage statuses are unchecked, meaning that all Requirements will be shown no matter of which coverage status they are. You can click on one or more statuses (Figure 6 - 7) and, in that case, Requirements will be filtered out, and they'll show if they match one of the selected statuses.
Next to each coverage status, you can quickly evaluate the total number of Requirements. This allows you to quickly find and analyze the Requirements that have problems or the ones that are not yet covered, for example.
Figure 9 - Filters
Options Menu
There is an options menu (Figure 9 - 3), accessible via the gear icon (Figure 9 - 2) where you can choose the visualization type for the report:
- Requirement Presentation:
- Hierarchical (Figure 9 - 3) - the parent/child relationship between Requirements will be shown in the report, up to two levels (e.g. Epic => Story). In this case, the filter needs only to include the parent requirements (e.g. "Epic").
- Flat (Figure 9 - 3) - the Requirement Issues will not consider the parent/child relationship. All parent and child Requirements will be considered and shown at the same level in the report, as long as the filter includes them.
- Hide Test Runs (Figure 9 - 4): hides the Test Runs column; this is quite useful when you are using Continuous Integration and you have multiple runs.
Analysis
On top of the report (Figure 9 - 5), it's possible to define the analysis strategy, i.e., the way you want to analyze the selected/filtered Requirements. By clicking the respective field (Figure 9 - 5), you can choose to analyze either by Version or Test Plan and complement it with an Environment.
- If you choose analysis by Version (Figure 10 - 1), then only the Test Executions for the specified version are considered.
- If the Environment is specified (Figure 10 - 2), then it considers only the executions within that environment. Click Apply (Figure 10 - 3) when you're done.
Figure 10 - Version
- If you choose analysis by Test Plan (Figure 11 - 1), then only the Test Executions (and related Tests and results) for the given Test Plan are considered for the calculation of the coverage status of each requirement.
- If the Test Environment is specified (Figure 11 - 2), then it considers only the executions within that environment. Click Apply (Figure 11 - 3) when you're done.
When you choose analysis by Test Plan (Figure 11 - 1), the Requirements are not filtered in any way. Therefore, if you want to restrict the list of Requirements that are being shown (e.g., just show the Requirements being indirectly covered by the Tests belonging to a Test Plan), you must always use the Filter options and eventually, some saved filter for that purpose (such as the testPlanRequirements JQL function).
Figure 11 - Test plan
Understanding the Report
The Issues and values that are shown in the report consider the options selected for analysis, namely, the relevant Test Executions and corresponding Test Runs (Figure 12 - 3) and Defects (Figure 12 - 4).
The report not only shows the traceability between entities but also presents some calculated values for the selected options. For example, the Requirement status (Figure 12 - 5) and the Test status (Figure 12 - 6) are shown in the Requirements (Figure 12 - 1) and Tests columns (Figure 12 - 2), respectively.
Figure 12 - Report
| Column | Notes |
|---|---|
Requirements | Requirements and the calculated Requirement status, considering the options selected for analysis |
| Tests | Tests and the calculated status, considering the options selected for analysis |
Test Runs | Test Runs and their status from all related Test Executions |
| Defects | Defects directly associated with the Test Runs, as well as those directly linked to the Tests (via a created Issue link) for the given version (through the AffectsVersion) |
The Defects that appear on a separate row (i.e., that are not related to a specific Test Run) contain all defects associated with the Test (Figure 13 - 1). In other words, it contains all defects linked to the Test, including the ones reported for Test Runs done on a different environment. This allows you to see all "related defects" that may or may not impact your version.
Figure 13 - Defects
Performance
In Continuous Integration scenarios, with thousands of Test Runs, showing all those Test Runs at the same time in this report may take some time and may overload your browser.
Xray will warn you beforehand whenever the total number of Test Runs exceeds a certain threshold.
Therefore, we advise you to hide the Test Runs column in the report (Figure 14 - 1), if the number of runs is considerably high (e.g. > 1000); the amount of information may overload your browser, and it will be hard for you to analyze the report with all that information.
Figure 14 - Test run
Hierarchy
In the following example (Figure 15), you can see the hierarchical relation between an Epic and some Stories (Figure 15 - 1). Once enabled, the hierarchy can be viewed as part of the report, and it supports a depth of up to five levels of Requirements.
Figure 15 - Requirements
Requirements with Labels or Statuses configured to be ignored in the Requirements Coverage settings will not appear on this report.
Exporting the Report
The report can be exported to a CSV file, which will include all report rows (and not just the visible ones).
Click Export (Figure 16 - 1) and select one of the two CSV options (Figure 16 - 2):
- Latest Test Runs.
- All Test Runs.
Figure 16 - Export
Regardless of the option made above (Figure 16 - 2), a modal will open (Figure 17). Select the CSV delimiter (Figure 17 - 3) and click Export (Figure 17 - 3).
Figure 17 - Export
You will get the CSV report file on your machine immediately.
Sharing the Report
The report can be shared by copying and sending the URL located in the browser's address bar (Figure 17 - 1).
When opening the report, the Analysis and Scope, Filter, and Requirement Presentation options will be automatically populated with the values provided in the URL.