Xray v3.0 introduces the Test Repository concept which allows hierarchical Tests organization at project level, by allowing users to organise organize Tests in folders.

This is a different approach from the traditional way of organising organizing Tests in flat lists by using Test Sets, 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 and prefer the Test Set approach.

Thus, a general setting enables users to globaly opt-in or opt-out of this hierarchical way of organizing Tests.

Key concepts

...

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

...

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. Besides this, Tests can also be moved between folders. The user can also choose the Tests to add to a given folder, by selecting the folder and choose the "Add Tests" context action for adding Tests using filters or JQL.

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

In a given parent folder, it is not allowed to have folders with similar names. For this, Xray does a case-insentive check of the trimmed folder name whenever you create or rename folder in order to evaluate if a similar folder already exists within its parent. This means that these folder names would all be considered to be the same: "  phanTom", "phantom", "PHANTOM". Please note that it is not allowed to use the "/" in the folder name.

Recommendations

• Think well how to structure the hierarchy of folders, having in mind that a Test may only be in folder; how would you organize them in your laptop if you were dealing with documents? Start by identifying the  folders that you want to put at the root and then try to drill-down on them, by creating 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 probably it won't work. Have in mind that a Test can only be part of a Test Repository's folder, while with Test Sets a Test may belong to several Test Sets  
• Avoid putting semantic related with the execution phase in the Test Repository or else your Test Repository will end messed up; Use the proper entities, such as Test Plans (and respective Boards) to make planning/execution related organization 

Test Repository vs Test Sets

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

The Test Repository concept is a bit different; you have to think a bit similarly to what.. the way you would organize your documents and files in your computer.

Thus, the two approaches offer advantages and have some possible drawbacks.

They can also work in a complementary way, if used properly in more advanced usage scenarios.

Pros and Cons

...