Migrate from Zephyr Squad

Introduction & contents

This document describes what kinds of test information users can import from Zephyr Squad into TestRail, how to export that data from Zephyr Squad, 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.

  Zephyr Squad migration sample files

For sample export/import files, download this attachment.

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.

Supported Limitations
  • Default fields
  • Custom fields
  • Preconditions
  • Test steps
  • Separated test steps
  • Attachments - Zephyr does not provide a bulk attachments export mechanism
  • BDD scenarios - Zephyr does not export BDD scenario details
  • Separated test steps custom fields - See workaround below


To import Test Cases with custom fields from Zephyr Squad to TestRail, matching custom fields must be created in TestRail first

Exporting test case data from Zephyr Squad

Zephyr Squad 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 Export Test Cases and then Export Excel (all fields). 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.


After the download has finished, you can see the file contains a structure similar to the one below.


Processing test case data

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

Zephyr Squad fields Zephyr Squad Excel columns TestRail fields
TestStep TestStep Steps(Step)
Test Result Test Result Steps(Expected Result)

Test Data
Custom Step Field 1
Custom Step Field 2

ADDITIONAL INFO Steps(Additional Info)

In the Excel file we exported on the previous step, you can see we have a field called “Custom Test Step Field 1”. 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 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.


After making this and any other changes you see necessary to your Excel file, you just need to save it as CSV in order to import your test cases to TestRail.


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.

  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 test cases and didn’t create the “Additional info” column on your excel file, just map “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. 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


Viewing imported data in TestRail

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.



Was this article helpful?
2 out of 5 found this helpful