Migrate from Zephyr Scale

Introduction & contents

This document describes what kinds of test information users can import from Zephyr Scale into TestRail, how to export that data from Zephyr Scale, and the steps they need to take to prepare and import that data into TestRail. And also describes what data can and cannot be imported, and offers workarounds for situations where data can't 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 that is supported when importing test cases via CSV and the limitations. While TestRail doesn’t support adding custom fields for separated test steps, we will guide you through how to import the values contained in these fields to the “Additional step information” field, so you won’t lose your data.

Exporting test case data from Zephyr Scale

Zephyr Scale supports exporting test cases in Excel format from the Test Cases search screen. To do so, simply select all the test cases you want to export, click More and then Export to Excel. This will trigger the export and download an Excel file to your local machine, which we will use to import your test case data to TestRail.

Processing test case data

Zephyr Scale supports three types of test case templates:

• “Plain Text”
• “Step-by-Step”
• “BDD - Gherkin”

When you export your test cases to Excel format, you’ll be able to observe that, depending on the type of template, the test script will be in different columns, as per the sample below.

On the table below, you can see how you should map the different Zephyr Scale templates to TestRail templates and how the columns should be mapped.

The fields that are common 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.

In case you are using multiple test case templates in your Zephyr Scale project, you need to create a separate CSV file for each. In order to do so, you can filter your Excel file depending on the values on the steps Test Script fields. One way you can infer the test case template is using the following filtering strategy:

After finalizing this process and any other changes you see necessary to your Excel files, you just need to save them as CSV in order to import your test cases to TestRail.

Processing Step-by-Step custom fields

As previously mentioned, TestRail doesn’t support custom fields within separated test steps, such as Zephyr Scale. In case you are using custom step fields, we suggest you map your custom step fields data as per the table below.

In the Excel file where you have filtered your Step-by-Step test cases, you can see we have a column called “Test Script (Step-by-Step) - Steps Custom Field (Text)”. In order to keep this data and import it as per the mapping on the table above, we suggest merging the information on this column with the information on the “Test Script (Step-by-Step) - Test Data” column and any other custom fields in a new column. To achieve this result, you can simply create a new column named “ADDITIONAL INFO” and use a formula similar to the one on the image below to merge the data with the original column titles and values, or you can create your own formula to format your data as it best suits you.

Importing test case data into TestRail

Importing test case data into TestRail is very straightforward. Just navigate to the project you want to import the test cases to and follow the steps below. This first walkthrough uses the Step-by-Step template file, which is the most complex one.

1. Navigate to the Test Cases page
2. Click the Import Cases icon on the top of the page and select Import from CSV
   
   
3. On the first step of the import dialog:
   1. Select the CSV file you want to import
   2. Select the Section you want the file to be imported to
   3. Set the CSV delimiter to be a comma (or the delimiter you used when saving the file)
   4. Set the Start Row to 1
   5. Set the Template to Test Case (Steps)
   6. Click Next
      
4. On the second step of the import dialog:
   1. Set the Row Layout to Test cases use multiple rows
   2. Map the CSV columns to TestRail fields (you can see a simple example on the image below)
   3. Check the option Ignore test cases/records without a title
   4. Click Next
      
      * If you didn’t have custom fields on Zephyr Scale test cases and didn’t create the “Additional info” column on your excel file, just map “Test Script (Step-by-Step) - Test Data” into “Steps(Additional Info)”.
5. On the third step of the import dialog:
   1. Select Remove HTML tags from CSV values for all fields
   2. Map Zephyr Scale values to TestRail values for dropdown fields
   3. Click Next
      
6. On the fourth and last step of the import dialog:
   1. Confirm the information processed by TestRail is as expected
   2. Click Import
      

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

By opening one of the test cases, you should be able to see the data was correctly imported, as per the image below.

In order to import the test cases with Plain Text and BDD - Gherkin templates from Zephyr Scale, you'll have to run the import using the Test Case (Text) template in TestRail, as per the mapping on the table below.

During the import wizard, there are only two differences:

1. On the first step of the import dialog, change the Template to Test Case (Text)
   
   
2. On the second step of the import dialog, set the Row Layout to Test Cases use a single row and map the Test Script (Plain Text) column (or the Test Script (BDD) column) to Steps in TestRail.
   

After following through with the import for both Plain Text and BDD templates, you should reach a result similar to the one for the Step-by-step template.