The Test Repository enables to view two types of organizing issues:

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

Users coming from legacy Test Management tools may find the approach of hierarchical organiztion through folders more natural and intuitive. Other organizations may prefer the Test Set approach instead.


Key Concepts


The Test Repository has two views, Folder and Test Set:


Folder view

The Test Repository Folder view 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 the selected specific folder.

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


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 and Preconditions 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 and Preconditions 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 and you can choose the Preconditions to add by using the Add → Preconditions 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

Test Set view


The Test Repository Test Set view is also a master-detail view. The master view (on the left) contains the Tets Sets of the respective project and the detail view (on the right) contains the tests belonging to the selected Test Set.

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.


To switch between the Folder view and the Test Set view you can click on the vertical tabs on the left:

Folder View



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


A: Folders section (master)

B: Tests section (detail)

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 and Preconditions 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 and Precondition 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 Precondition 

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

In order to create a Precondition in a folder,

Step 1: Right-click on the folder.

Step 2: Click on Create → Precondition.

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

Add Precondition

You can "add" Preconditions 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 Precondition 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 Preconditions to a folder,

Step 1: Right-click on the folder.

Step 2: Click on the Add→ Preconditions.

Step 3: Choose the Preconditions 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 and Precondition 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 and Preconditions

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

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


Filtering by text:

Filtering by custom filters:

Showing only issues assigned to you:

Showing only Tests or Preconditions or showing both types of issues:

Moving to another folder

Tests and Preconditions 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) or the same for Preconditions from folder to folder within the Test Repository.

Ordering / Ranking

Tests and Preconditions 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 and Preconditions.

Add to Test Set(s)

Use the action Add Tests to Test Set to add selected Tests and Preconditions 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 or Precondition issue

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

It can also be reached form the Precondition issue page in the Precondition details section:

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

Xray History

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


Test Set View

The image below depicts the several key areas od the Test Repository Test Set view screen

A: Test Sets section (master)

B: Tests section (detail)

Test Set Actions


Filtering Test Sets

It's possible to filter the Test Sets by using custom filters.

Sorting Test Sets

It's also possible to sort Test Sets by a specific field.

Test Sets can be sorted in ascending or descending order.

View Issue

The Test Set can be viewed in the respective issue page through a dialog by selecting this action.


Delete

This action will delete the Test Set from Jira.

Create a Test

Create a Test and add it to the respective Test Set:


Create Test Set/Test Plan/Test Execution with Tests

Create a Test Set or Test Plan or Test Execution and add the Tests of the respective Test Set

Add Tests

Add existing Tests to the respective Test Set


Add Tests to Test Set/Test Plan/Test Execution

Add the Tests in the respective Test Set to another Test Set or existing Test Plan or existing Test Execution


Test Actions

By selecting one or multiple Tests from the detail view and clicking on the right mouse button key you have access to multiple actions:

View Issue/View Issues in Navigator

View the selected Test in an issue page or view multiple selected Tests in the navigator page.


When only one Test is selected:

When multiple Tests are selected:

Create Test Set/Test Plan/Test Execution with Tests

Create a Test Set or Test Plan or Test Execution and add the selected Tests.

Add Tests to Test Set/Test Plan/Test Execution

Add selected Tests to existing Test Sets/Test Plans/Test Executions.

Change Rank

Change the rank of a selected Test within the respective Test Set.



Remove from Test Set

Remove the selected Tests from the respective Test Set.

Delete

Delete a selected Test from Jira.