Requirements and sub-requirements

Sometimes a given feature may be decomposed in multiple individual and granular parts, each one delivering a subset of value. Generally speaking, a given requirement may be decomposed in multiple sub-requirements, each one covered by one or more Tests.

If you’re familiar with Agile, you’ll know that Epics and User Stories map perfectly to this concept.

So, how can you use sub-requirements in Xray?

Configuring Sub-Requirements

The requirement => sub-requirement relation can be defined in the Issue Type Mapping configuration section of Xray.

There are 3 different ways to define what is a sub-requirement:

  • it may be a Story, through the standard Epic => Story relation
  • or a sub-task issue of a given requirement
  • or an issue linked with the requirement through a given Issue Link Type, in the specified direction

Configuration of Sub-Requirements

Note that in any case, the sub-requirement issue types must also be defined as “Requirement Issue Types” in the Issue Type Mapping configuration.

The following diagrams summarize the different ways Xray considers issues as “sub-requirements” of a given “requirement”.

Working with sub-requirements

Requirements may be validated directly, by covering them also directly with Tests, or through the sub-requirements. Sometimes, when you don’t have a complete decomposition, you may even have the case where you cover both your parent requirement explicitly and also your sub-requirements.

Let’s imagine we have a parent requirement with two sub-requirements, or to be precise, an Epic with two user stories in a perfect decomposition scenario. Each user story is covered individually by two different Tests.

In the Epic issue screen, the Test Coverage panel will show that it is covered by 4 Tests.

The Epic’s “Requirement Status” field indicates that is failing for version 3.0, since one of the user stories is failing (because one of Tests is failing, as you can see if you put the mouse over it).

If we go to the “Requirement Coverage” project tab, select “Overall Coverage Chart”, and click on the bar chart related with the failing requirements, we can see a list with those requirements.

This list contains the Epic issue and by clicking on the arrow we are able to see the related user stories (i.e. sub-requirements) and their individual completeness state.

Note that the Epic row takes into account the values of the user stories.

The following question arises…

How is the Requirement Status calculated when we have sub-requirements?

Calculation of Requirement Status

Requirement issues have the Requirement Status custom field, which is a calculated field that gives you a glimpse of the status of the requirement (depending on the configuration).

If a requirement has no tests directly associated with it, then the status of the requirement reflects the status of the sub-requirements. Thus, a requirement is considered OK if all the sub-requirements are also OK; it will be NOK, if one the sub-requirements is NOK.

The following table shows the calculated value for the Requirement Status, given the status for the isolated parent requirement and the status of a given sub-requirement.

Whenever you have tests directly linked to the parent requirement, Xray considers that you are validating the requirement directly, thus it’s irrelevant if the sub-requirements are uncovered by tests. However, if one of sub-requirements is NOK, then the parent requirement will be also NOK.

In sum…

By using sub-requirement issues, it facilitates the management of epic/huge requirements and makes their coverage analysis easier.

Sub-requirements may be individually covered and their status will be reflected on the “parent” requirement.

Learn more…



  • I have made a parent child configuration using the third option (link). Both my objects are requirement types. In this case we are using Criteria of a User story to map directly to a Requirement issue type. The Requirement issue type is in JIRA Project A and the Criteria is in Project B. When i run the traceability report it does not show the releationship and will only show Criteria or Requirements depending on which project i run from. Do i have to have both the Parent and Child in the same project?

    • Hi Drew,
      Yes, to generate complete Traceability with the parent/child configuration, the requirements have to all be in the same project. Hope this helps!

      Best regards,
      Team Xray

Leave a reply