Migrate from Xray (Cloud)

Introduction & contents

This document provides information on the types of test information that users can import from Xray (Cloud) into TestRail, the process of exporting data from Xray, and the necessary steps for preparing and importing that data into TestRail. It also outlines what data can and cannot be imported and provides workarounds for situations where data cannot be imported into TestRail.

Features & limitations

TestRail supports importing test cases with all the supported fields, from header fields to template fields, including separated test steps and custom fields, via CSV. The table below enumerates the data supported when importing test cases via CSV, as well as the current limitations.

To import test cases with custom fields from Xray to TestRail, it is necessary to create matching custom fields in TestRail prior to the import process.

Exporting test case data from Xray(Cloud)

To have complete control over the layout and format of your Xray data exports, you can use the Xray Document Generator. This feature allows you to create your own custom templates and generate documents that reflect your Jira data, primarily Xray issues, requirements, and defects.

To export test cases from Xray in a format which allows you to import them to TestRail, we'll guide you through the following steps:

• Creating a new template in Xray (Cloud) using Document Generator
• Exporting test cases from Xray (Cloud) using the new template

Creating a new template in Xray (Cloud):

• Navigate to the project in Jira from which you want to export the tests
  
  
  
  
• Navigate to Project Settings > Xray Settings
• Under Xray Settings, click on the Document Generator link from the left navigation panel
  
  
  
  
• Click on the Add button
  
  
  
  
• In the Add Template screen, provide the information shown below
  
  
  
  
  
  
  • Name: The name field will be used in the template store to save the template. This name is also the one that will appear in the template selection drop-down when exporting data. For this tutorial, we used TestRailMigrationTemplate
  • File: The file containing the export template configuration. To export test cases in a format compatible with TestRail, use our XrayTestReportTestRail.xlsx template file
  • Scopes: Scopes refer to the specific areas or sections within Jira where the newly created template is accessible. This tutorial focuses on two scopes, Issue Navigator and Issue Details
  • Entities: These are the Jira entities for which you would like the template to be accessible. In this tutorial, we focused on Test as an entity as we are interested in exporting the tests from Xray to TestRail, and this entity is included by default
  • Output Formats / Default Format: Once you upload the file, these fields will be automatically set to XLSX, as per the template configuration
• Click the Save button and the new template will be available under the Document Generator Templates.
  
  

Exporting test cases from Xray Cloud with the help of the new template

• On the Jira issues navigator, use a filter to find the test cases you want to export. We recommend using the following criteria:
  • filter by your desired project
  • issuetype should be Test
  • Test Type must be Manual
  
  
  
  
• Click on Go to all issues
  
  
  
  
• Click on the Xray - Document Generator option under Apps
  
  
  
  
• In the Xray - Document Generator dialog, select the TestrailMigrationReport as the Template and XLSX as an Output Format and click the Export button
  
  
  
  
• A XLSX file similar to Issues.xlsx should be generated
  
  
  
  
• Click Download to save the file to your local computer and then convert the XLSX file to CSV so it is compatible with the TestRail import wizard

Importing test cases to TestRail

The common fields to all templates can be mapped to TestRail fields as per the table below. For fields that may not exist by default in TestRail, you can create a new custom field to map your data to.

Importing test case data into TestRail is very straightforward. Just navigate to the project to which you want to import the test cases and follow the steps below.

• Navigate to the Test Cases page
• Click the Import Cases icon on the top of the page and select Import from CSV
  
  
  
  
• On the first step of the import dialog:
  • Select the CSV file you want to import
  • Select the Section you want the file to be imported to
  • Select the File Encoding as Windows-1252(Latin)-Excel default. This is the default file encoding used by Excel
  • Set the CSV delimiter to be a comma (or the delimiter you used when saving the file)
  • Set the Start Row to 1
  • Is header row checkbox should be checked as our Excel sheet includes a header row
  • Set the Template to Test Case (Steps)
  • Click Next
    
    
    
    
• On the second step of the import dialog:
  • Set the Row Layout to Test cases use multiple rows
  • Set the Column to detect new test cases value to Summary. This means new test cases will be detected based on the different summaries available
  • Map the CSV columns to TestRail fields (you can see a simple example in the image below)
  • Check the option Ignore test cases/records without a title
  • Click Next
    
    
    
    
• On the third step of the import dialog:
  • Select Remove HTML tags from CSV values for all fields
  • Click Next
    
    
    
    
• On the fourth and last step of the import dialog:
  • Confirm the information processed by TestRail is as expected
  • Click Import
    
    
    
    
• Once the import is done, you will get the confirmation dialog, as shown in the screenshot below.
  
  

Viewing imported data in TestRail

You should now see your imported test cases as per the image below.