Xray v3.0 introduces hierarchical Tests organization both at the project level (via the Test Repository) and at Test Plan level (via the Test Plan Board).

While the Test Repository deals with the organization of Tests within the scope of a given project during the specification phase, the Test Plan Board is all about the organization at planning level (and as consequence, at the execution level).

A Test Plan contains a group of Tests that you want to validate, and aggregates the results from multiple iterations (i.e., Test Executions).

For a given Test Plan that is tracking a group of Tests (e.g., a test plan for regression testing or a test plan for new features), you may want to organize the Tests by component, by sub-system, by functionality or by any other criteria.

The Test Plan Board enables you to organize the Tests that are part of your Test Plan in multiple folders and sub-folders. Implicitly, you can also define the order of the Tests and the relevance of those grouped Tests (i.e., folders) by ranking them within the tree presented within the Board.

By providing you the ability to define groups and sub-groups (i.e., folders and sub-folders) for the Test Plan's Tests, you're able to track them independently and see right away their current status, even if the scope of the Test Plan is broader. You can also more easily do operations for those subsets of Tests, such as creating Test Executions.

This hierarchical approach is different from the traditional, flat way of organizing Tests inside the Test Plan, which was the only available before Xray v3.0.

Users coming from legacy Test Management tools may find this way more natural and more intuitive. Other organizations may prefer to not enable this feature at all.

Thus, a general setting enables you to globally opt-in or opt-out of this hierarchical way of organizing Tests inside the Test Plan.

Key concepts

Within the Test Plan Board screen, you can see some meta-folders that provide you quick ways to see or filter relevant Tests. These folders are read-only and will be used mainly as basis to select the proper Tests before adding them to folders within the Test Repository itself.

  • All: all Test issues that are part of the Test Plan, ordered by their Test Plan rank
  • Orphans: all non-organized Test issues (i.e., Tests that are not part of the Board), in the context of the current Test Plan

Aside from these folders, you can also see the Board itself, which contains the hierarchically organized tests for this Test Plan.

  • Board: the actual Test Plan Board composed of multiple folders and sub-folders along with the Tests, in the context of the current Test Plan. It corresponds to the root folder.

Within the Board root folder, multiple folders can be created and Tests can be added to them. The root folder may only contain folders. Similar to traditional operating systems (e.g., Windows, OSX, Linux), Tests may only be part of one folder.

Tests can be "added" (i.e., moved) from the All or from the Orphans meta-folders to the destination Board's folder by selecting and moving them using drag-and-drop. Tests can also be moved between folders. You can also choose the Tests to add to a given folder by selecting the folder and choosing the Add Tests context action for adding Tests using filters or JQL.

Folders can be created at the root of the Test Plan Board or in any (sub)folder within it.

In a given parent folder, folders must not have similar names. For this, Xray does a case-insensitive check of the trimmed folder name whenever you create or rename folder. This means that these folder names would all be considered the same: "  phanTom", "phantom", "PHANTOM". Moreover, folder names must not use the "/" character.


The Test Plan Board scope is related to its Test Plan; thus, the kind of concerns you have with it are different from the ones you may have with the Test Repository.

With the Test Plan Board, consider the hierarchy of folders, keeping in mind that a Test may only be in one folder.

These questions may help you out defining a better structure for your Board:

  • What things (i.e., Tests) are most relevant and shall be executed first?
  • What things do you want to track and manage (e.g., schedule executions) independently?

Test Plan Board vs Test Repository

The two are completely different because their scope is different.

The Test Repository is a project-level organization of all the Tests contained within a given project. Thus, it's something with a more broader scope, where one or more authorized users organize the Tests in multiple folders, in some logical way, without being concerned with the execution-related aspects. Thus, the Test Repository can be used as a basis for creating some other entity, such as Test Sets, Test Plans, and Test Executions.

The Test Plan Board is a Test Plan-level organization; it allows users responsible for dealing with Test Plans to structure them plans more effectively, so they can give priority to the execution of some Tests, and also have clear visibility on how different sets and subsets of tests are within the Test Plan.

Regardless of the way you organize the Tests within the project, by using the Test Repository, you may choose how to organize Tests within each Test Plan. By using the corresponding Test Plan Board, you gain finer visibility of the current status of different subsets of Tests and also to schedule executions for them.

Pros and Cons

The following table summarizes some pros and cons of using the Test Plan Board.

  • More user-friendly way of managing the Test Plan and its Tests
  • Enhanced visibility over certain groups of Tests that are part of the Test Plan and greater flexibility on doing operations over them
  • Some additional complexity


Learn more

For a full comprehensive list of the available operations and how to perform them, please check Test Plan Board.


Do I have to use the Board in order to organize the Tests in a given Test Plan?

No. You can simply use the standard flat organization, right on the issue screen of the Test Plan where you can also rank the Tests the way you want. You get to choose whether to use the Board for a Test Plan or not.  

Are there any advantages to using the Board even if I don't want to use hierarchical test organization?

Yes. You have the

  • ability to easily see the overall progress of all Tests, in a given Test Environment
  • ability to easily filter out the Tests you want, for scheduling Test Executions

Can I use the Test Plan Board and not the Test Repository?

Yes. Both are enabled based on the same setting in the Xray preferences. However, the Test Repository will only be available for users with certain role(s), as defined also in the Xray preferences.