The Test Repository enables the hierarchical organization of Tests at the project level by allowing you to organize Tests in folders and sub-folders.

Always keep in mind that each project has its own Test Repository and that a Test can only belong to one folder within the Test Repository. 

This is a different approach from the traditional way of organizing Tests in flat lists by using Test Sets.

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

Key Concepts

The Test Repository is a master-detail view. The master view (on the left) contains the folder hierarchy while the detail view (on the right), contains the tests belonging to a specific folder.

At the root of the Test Repository you will see the Test Repository folder, this folder has the following characteristics:

• It corresponds to the root folder;
• Is read-only; meaning it can't be deleted or renamed.
• Is composed of multiple folders and sub-folders along with Tests, in the context of the current project;
• Contains all non-organized Test issues (i.e., Tests that are not part of any folder), 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. Tests may only be part of one folder.

Tests can be "added" (i.e., moved) from the Test Repository folder 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-sensitive check of the trimmed folder name whenever you create or rename a folder. This means that these folder names would all be considered different folders: "  phanTom", "phantom", "PHANTOM". Moreover, folder names must not use the "/" or "\" characters.

Recommendations

• 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 on 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. 

Overview of the Test Repository UI

The Test Repository screen can be accessed from the project left sidebar by clicking on the "Testing Board" option and then Test Repository.

The image below depicts the several key areas of the Test Repository screen, which include the Test Repository itself, along with some auxiliary folders.

A: Folders section (master)

• • A1: the Test Repository root folder, composed of folders and sub-folders with Tests organized within them
  • A2: a given folder; CRUD actions for the selected folder (e.g., create, rename, delete) can be accessed by right-clicking on the folder
  • A3: information about the number of Tests within the current folder and the total Tests, including sub-folders
  • A4: context actions for the currently selected folder; these actions are also accessible by right clicking on a folder. 
    
    

B: Tests section (detail)

• • B1: the complete path of the folder
  • B2: filter for Tests 
  • B3: additional information about the shown (filtered) Tests versus the actual total number of Tests within the current folder 
  • B4: a ranked list of Tests within the current folder (only direct children)

C: Switch between "flat view" and "folders view" 

View Mode: Flat or Hierarchical

You can choose between the traditional, hierarchical/folders view or a flattened view.

If you choose "Folders View" then in the Tests section (B) you will see just the Tests that are direct children of the folder selected in the left side, within the Folders section (A). In this case, you can only select Tests directly within the currently selected folder.

On the other hand, if you prefer you can switch to a "Flat View";  if so, you'll see on the right side (Tests section) all the Tests that belong to that folder and related sub-folders, grouped by folder. Then you can apply a filter if you want, select some of the Tests (no matter in which sub-folder they're in) and do an operation for them.

Folder Actions

A folder can be selected by clicking on it. Once selected, you can perform context actions or use the icons available at the top of the folders' section.

Note: It is not possible to select multiple folders.

Create

To create a new folder:

Step 1: Click on the parent folder.

Step 2: Click on the add icon at the top of the folders section.

Step 3: Type the name for the folder on the create folder dialog.

Step 4: Press "Create" to create the folder.

Rename

To rename an existing folder:

Step 1: Right-click on the folder you wish to rename.

Step 2: Click "Rename Folder."

Step 3: Type the new folder name on the rename dialog.

Step 4: Press "Rename" to rename the folder.

Remove

You can easily remove an existing folder and its descendant folders.

Tests that were in one of the removed folders will not be erased. Tests will be removed from the Test Repository but will appear in Test Repository folder, so they can be organized in the Test Repository again if needed.

In order to remove a folder:

Step 1: Right-click on the folder you wish to rename.

Step 2: Click on Delete Folder.

Step 3: Confirm the removal of the folder.

Expand/Collapse

Folders can be expanded or collapsed easily just by clicking the folder's icon.

Collapse All

The collapse all folders action is available on the top folders section.

In order to collapse all the folders of the Test Repository:

Step 1: Click on Collapse All action in the top folders section.

View Issues

You can view the Test issues, from the selected folder and from its subfolders, in the issue search screen.

In order to view the Test issues:

Step 1: Right-click on the folder.

Step 2: Click on View Issues.

A new tab will be open that will take you to the search issues page

Moving to another folder

A folder, including its descendants, can be moved to another folder just by dragging-and-dropping to the destination folder.

Dragging the folder directly on top of some existing folder will append it to the list of current child folders.

Ordering / Ranking

You can also move directly to a given position/rank by choosing the interim space between two existing folders.

Note: If you wish to rank it as the last one (i.e. move it to the last position) within some parent folder, you just need to drag it to the parent folder.

Creating a Test 

You can create a Test and associate it automatically with the selected folder.

In order to create a Test in a folder,

Step 1: Right-click on the folder.

Step 2: Click on Create Test.

Step 3: Fill out the Test fields and click Create. Your brand-new Test and associated with the selected folder.

Add Tests

You can "add" Tests to an existing folder based on some filters or JQL.

This action corresponds to "moving" them from any folder they may already be in (including the Test Repository) to the destination folder. Thus, if you "add" a Test that is currently in some folder within the Test Repository to some destination folder, then it will essentially be moved from the source folder to the destination folder.

In order to add Tests to a folder,

Step 1: Right-click on the folder.

Step 2: Click on the Add Tests.

Step 3: Choose the Tests you want using the provided filters, a previously saved filter or by JQL.

Creating a Test Set

You can easily create a Test Set using all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Set will respect the ranking they already have in the Test Repository folder.

In order to create a Test Set with all the Tests in a given folder, including its descendants:

Step 1: Right-click on the folder.

Step 2: Click on the Create Test Set with Tests.

Step 3: Fill out the Test Set fields and click Create. Your brand-new Test Set is created with all the Tests, in the proper order.

Add to Test Set(s)

You can add Tests to an existing Test Set with all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Set will respect the ranking they already have in the Test Repository folder. If Tests already exist in the destination Test Set, then their ranking in the Test Set is not changed.

In order to add Tests from a folder, including its descendants, to some existing Test Set(s):

Step 1: Right-click on the folder.

Step 2: Click on the Add Tests to Test Set.

Step 3: Choose the Test Set(s) key(s) and select Add Selected. The Test Set(s) will now be updated.

Create Test Execution

You can easily create a Test Execution using all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Execution will respect the ranking they already have in the Test Repository folder.

In order to create a Test Execution with all the Tests in a given folder, including its descendants:

Step 1: Right-click on the folder.

Step 2: Click on the Create Test Execution with Tests.

Step 3: Fill out the Test Execution fields and click Create. Your brand-new Test Execution is created with all the Tests, in the proper order.

Add to Test Execution(s)

You can add Tests to an existing Test Execution using all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Execution will respect the ranking they already have in the Test Repository folder. If Tests already exist in the destination Test Execution, then their ranking in the Test Execution is not changed.

In order to add Tests from a folder, including its descendants, to some existing Test Execution(s):

Step 1: Right-click on the folder.

Step 2: Click on the Add Tests to Test Execution.

Step 3: Choose the Test Execution(s) key(s) and select "add selected." Test Execution(s) will now be updated.

Create Test Plan

You can easily create a Test Plan using all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Plan will respect the ranking they already have in the Test Repository folder.

In order to create a Test Plan with all the Tests in a given folder, including its descendants:

Step 1: Right-click on the folder.

Step 2: Click on the Create Test Plan with Tests.

Step 3: Fill out the Test Plan fields and click Create. Your brand-new Test Plan is created with all the Tests, in the proper order.

Add to Test Plan

You can add Tests to an existing Test Plan using all the Tests in a given folder and its descendant folders.

The ranking of the Tests within the Test Plan will respect the ranking they already have in the Test Repository folder.

In order to add Tests from a folder, including its descendants, to some existing Test Plan(s):

Step 1: Right-click on the folder.

Step 2: Click on the Add Tests to Test Plan.

Step 3: Choose the Test Plan(s) key(s) and select Add Selected. Test Plan(s) will now be updated.

Test Actions

Tests can be selected by clicking on them. Multiple selections are possible by using the "Ctrl" key (on Windows) or the "Cmd" key (on OS X). If you want to select more than one Test and the Tests are listed consecutively, use the "Shift" key to quickly select an entire group. Click the first Test in the list you want to select, hold down the "Shift" key, scroll down to the last Test you want and click it. This selects the first item, the last item and all items in between.

You can filter the list of visible Tests to make it easier to pick the Tests you need.

After selecting one or more Tests, context actions can then be done on them, such as creating a Test Set, Test Execution, etc.

Filtering visible Tests

The list of visible Tests can be filtered, so you can easily see and obtain the relevant Tests you need. Note that the filter is applied when you change to another folder.

Filtering Tests is quite useful, for example, when creating the structure of the Test Repository based on a subset of Tests from the Test Repository folder.

Moving to another folder

Tests can be moved to another folder just by dragging-and-dropping to the destination folder.

You can also use this operation for "moving" Tests (i.e., adding Tests) from folder to folder within the Test Repository.

Ordering / Ranking

Tests can be ranked within a folder by using drag-and-drop.

Create a Test Set

Use the action Create Test Set with Tests to create a new Test Set containing the selected Tests.

Add to Test Set(s)

Use the action Add Tests to Test Set to add selected Tests to an existing Test Set.

Create Test Execution

Use the context action Create Test Execution with Tests to create a new Test Execution containing the selected Tests. 

Add to Test Execution(s)

Use the context action Add Tests to Test Execution to add selected Tests to an existing Test Execution. 

Create Test Plan

Use the context action Create Test Plan with Tests to create a new Test Plan containing the selected Tests.

Add to Test Plan(s) 

Use the context action Add Tests to Test Plan to add selected Tests to an existing Test Plan.

Move to Root

You can move Tests to the Test Repository (Root) folder; this is equivalent to removing them from the Test Repository.

There are 2 different ways to move Tests to the Test Repository folder:

First option:

Step 1: Select the Tests you want.

Step 2: Drag the Tests to the Test Repository folder.

Second option:

Step 1: Select the Tests you want.

Step 2: Use the context action Move to Root.

View Issues

You can use the context action View Issues to view the selected Tests in the search issues page.

Step 1: Select the Tests you want.

Step 2: Use the context action View Issues.

How ranking works when creating, or adding Tests to Xray entities

When creating a Test Set, Test Execution or Test Plan, or adding Tests to an existing one, Xray will respect the order of the Tests, taking into account the ranking they have in the Test Repository.

The algorithm starts by adding the Tests of the folder, respecting their rank in the folder, and then iterates through the child folders. Each child folder is processed the same way.

If a Test already exists in the destination entity (e.g. Test Set/Plan/Execution), then it is not added again and the current ranking is maintained.

How to take advantage of the folder hierarchy outside the Test Repository

Ok, now you have a place to organize your tests in a tree. How can you use this information outside of the Test Repository?

Whenever adding Tests to a Test Set, a Pre-Condition, a Test Plan or a Test Execution, it is possible to filter by the Test Repository folder. Just choose the "Search" tab on the Xray issue picker dialog and use the Folder filter. 

Using this filter, you can create any of these entities just for the Tests in the selected folder.

It is also possible to include all Tests from sub-folders as well. In other words, all descendent Tests of the selected folder will be included.

How to go to the Test Repository from a Test issue

The Test Repository can be reached from the Test issue page in the Test Details section:

The location of the test within the Test Repository is shown and each of folders in the Test's path is clickable to send the user to the respective folder.

Xray History

Moving Tests between folders on the Testing Repository records the changes on the Xray History of each Test (see Test issue page).