Xray v3.0 introduces the Test Repository concept which enables the hierarchical organization of Tests at the project level by allowing you to organize Tests in folders.

This is a different approach from the traditional way of organizing Tests in flat lists by using Test Sets, which was the only available method before Xray v3.0.

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

Thus, a general setting, available in Global Preferences, allows you to globally opt-in or opt-out of this hierarchical way of organizing Tests.

Key concepts

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

  • All: all Test issues within the current project (regardless of whether they're organized or not)
  • Orphans: all non-organized Test issues (i.e., Tests that are not part of the Test Repository), in the context of the current project

Aside from these folders, you can also see the actual Test Repository, which contains the hierarchically organized tests.

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

Within the Test Repository 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 Test Repository folder by selecting and moving them using drag-and-drop. Tests can also be moved between folders. You can choose the Tests to add to a given folder by selecting the folder and clicking the Add Tests context action.

Folders can be created at the root of the Test Repository 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 following characters: "/", "\", apostrophe, "*".


  • Carefully structure the hierarchy of your folders, keeping in mind that a Test may only be in a single folder. How would you organize them in your laptop if you were dealing with documents? Start by identifying the folders that you want to place at the root, and then try to drill down and create sub-folders that are relevant to you.
  • If you're already using Test Sets, don't try to replicate the Test Sets model in the Test Repository because, most likely, it won't work. Again, a Test can only be part of one folder in the Test Repository; with Test Sets, a Test can belong to several Test Sets.  
  • Avoid semantics when it comes to the execution phase or else, your Test Repository will get messed up. Use the proper entities, such as Test Plans (and corresponding Boards) to make planning/execution-related organization. 

Test Repository versus Test Sets

Test Sets are simple, flat lists of Tests that you can use as basis for creating Test Executions or Test Plans. Since the Tests are grouped in some logical way (e.g., grouping all Tests related with regression testing or security or all Tests for a specific component or some high-level feature/business case), a Test can be part of different Test Sets. Test Sets can also be used as a dynamic way to cover requirements.

The Test Repository concept, on the other hand, is similar to the same way you would organize your documents and files in your computer.

Each approach offers advantages and have some possible drawbacks, but they can also work in a complementary way. If used properly, you can use both in more advanced usage scenarios such as using Test Sets to cover complex requirements and using the Test Repository to organize the Tests.

Pros and Cons

  • Hierarchical concept, similar to computer file systems, may be easier to understand especially for users coming from legacy Test Management tools
  • Can operate alongside an existing Test Set (but consider carefully if you want this additional "complexity")
  • A Test can only be in one folder so it cannot be categorized in multiple ways simultaneously (as you can do by using labels)
  • A folder cannot be used as a way to cover requirements; Test Sets can
  • Test Sets can also be used as a dynamic way to cover requirements; Test Repository folders can't

Cloning/moving a Test Issue

The Test Repository Path of a Test issue is copied to the cloned issue whenever using the Clone/Move from Jira, Clone Plus for Jira or Bulk Clone Professional for Jira assuring that the repository holding the cloned issue has all the folders needed to support the path of that issue.


Learn more

For a full comprehensive list of the available operations and how to perform them, please check Working with the Test Repository.