What you'll learn

  • How to export test cases from Zephyr Squad
  • Use a script to convert the exported Excel test cases to an Xray compatible CSV file
  • Import different test cases (with different fields and options)
  • Validate that the test cases were imported to Xray

Source-code for this tutorial

  • All examples are available on GitHub

Overview

This tutorial explains how to export test cases from Zephyr Squad and import them into Xray.

Zephyr Squad is a test management tool running in Jira with versions available on-premises and in the cloud. In this tutorial, you will learn how to export the test cases from Zephyr Squad in an Excel format, how to use a script (available in GitHub) to convert the Excel file into a compatible CSV so that it can be imported into Xray using the Test Case Importer.

This tutorial will provide examples of exporting and importing test cases from Zephyr Squad into Xray.

Features and Limitations

Below is a list of the support features and current limitations.

Migration from Zephyr Squad is limited by the information we can export from Zephyr Squad and how it can be mapped to Xray entities.

Most of the test case information will be migrated seamlessly, but please check the following table for more details.

Supported FeaturesUnsupported
  • Test and Test steps
  • Test case attachments
  • Test Cycles
  • BDD Tests
  • Test Executions
  • Defects and Requirements


How it works

Zephyr Squad is an add-on that can be enabled in your Jira project and allows the users to specify tests. Zephyr Squad has test cycles and executions; these concepts help the organization and execution of test cases. Depending on your testing goals, you can use one or another.

Zephyr Squad can create detailed test cases, lite, or use a BDD approach (with Gherkin). The test case using the detail or lite approach allows the user to define multiple steps with test steps, test data, and test results. The BDD approach enables the user to define scenarios in Gherkin.

In Zephyr Squad, to be able to execute tests, you need to associate them with a test cycle.

Zephyr Squad uses different entities to describe tests and the flow, so we have summarized the possible mappings between Zephyr Squad and Xray in the next table.

Zephyr SquadXrayComments
Test CaseTest

All three types of tests from Zephyr are imported into Xray.

The test case attachments are not exported using Excel export option in Zephyr Squad.



Prerequisites


We will use the built-in Test Case Importer feature for these examples, available when you install Xray in your Jira instance.

We will need:

  • Access to Zephyr Squad instance to export test cases in Excel format
  • Access and usage of scripts to convert Zephyr Squad Excel test cases to CSV Xray import files
  • Access to a Jira instance with Xray installed
  • Only users with the Make Bulk Changes permission will have this option available. Additionally, the user will only be able to import data into projects where he has the Create Issues permission.



Examples

In each example, we will show how we obtained the Excel file from Zephyr Squad, how to use the scripts to convert the Excel files into compatible CSV files, and finally, how to import the CSV files into Xray.

We will showcase different possibilities when exporting test cases from Zephyr Squad that should cover most usages.

On GitHub you can find the files used to support the examples in this tutorial, including the Excel file exported from Zephyr Squad, the CSV file with the definition of the test cases to import, and a configuration file that will configure all associations and fields for the importation to be successful.


Export to Excel from Zephyr Squad and Import into Xray

In Zephyr Squad, when you choose to export using Excel format, it will export the selected test cases. In this example, we are exporting all test cases.

To export from Zephyr Squad, we are using the Export Excel (all fields) option in the Export Test Cases right upper menu entry in Zephyr Squad.


Looking into more detail on what we have in Zephyr Squad, we have several test cases defined, covering the different types available in Zephyr Squad. One behaviour-driven development test case with one scenario in Gherkin, one "Detail" test case and a "Lite" test case using some variations in the steps available (tables, images, different formats, etc.). All of the details of each case are described below.

The file generated by Zephyr Squad can be found in ZFJ-issue-export.xlsx.

To import into Xray, we created one script to convert this Excel file into a CSV-compatible file that can be imported into Xray.
The script will parse the Excel file and create a CSV variant that can be imported into Xray.

To execute the script, use the following command:

python3 zephyrsquad2Xray.py -i ZFJ-issue-export.xlsx -o ZFJ-issue-export.csv


The output file has all the test steps from Zephyr Squad.

comic_estore.csv 
Issue ID,Issue Key,Test Type,Test Summary,Test Priority,Action,Data,Result,Issue Type,Labels,Component,Description,Links
1,,Manual,Scenario outline,3,,,,Test,,,,
2,,Manual,My second Test Zephyr Squad (Detail),3,"First test step Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","test Data Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","test Result Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|",Test,,,"My second Test Zephyr Squad

*Bold*
_Italic_
+Underline+

List
* One
* Two
* Three

Table


||Heading 1||Heading 2||
|Col A1|Col A2|
",
2,,Manual,,3,"Second step Zephyr Squad Details

[Atlassian|http://atlassian.com]","Test Data Zephyr Squad Details

[Atlassian|http://atlassian.com]","Test Result Zephyr Squad Result
",Test,,,,
3,,Manual,My first Zephyr Squad Test (Lite),3,First step of Zephyr Squad first test,Test Data of Zephyr Squad first test,Test Result of Zephyr Squad first test,Test,,,Description of the Zephyr Squad Test,
3,,Manual,,3,"Second Step of Zephyr Squad
*Bold*
_Italic_
+Underline+",Second Step Test Data,Second step test result,Test,,,,
3,,Manual,,3,"Third Step

Table

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","Third Step Test Data

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","Third Step Test Result

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|",Test,,,,


To import it into Xray, we use Test Case Importer feature with the recently created CSV file; you can use the configuration file provided with the .json extension (importConfiguration.json).


When the import operation is complete, you can download the operation details, save the configuration for future use, or check the created issues.

When you click over the link to see the imported issues, we can see that it has created three issues with all the properties defined in the CSV.


More Details

Let's look into some specificities of this approach and some test particularities.


Detail and Lite Tests into Manual Test Cases

Zephyr Squad allows you to create Manual Test Cases with steps (using test steps, test data, and test results) to describe the test.

We have created one test case using the steps in Lite mode and one in Detail mode (the corresponding exported Excel file: ZFJ-issue-export.xlsx).


After running the script that converts this Excel file into a CSV file we can see that each Test is created and the steps are filled with the information extracted from the Excel file.

Manual Tests in comic_estore.csv 
Issue ID,Issue Key,Test Type,Test Summary,Test Priority,Action,Data,Result,Issue Type,Labels,Component,Description,Links
1,,Manual,Scenario outline,3,,,,Test,,,,
2,,Manual,My second Test Zephyr Squad (Detail),3,"First test step Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","test Data Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","test Result Zephyr Squad Details

*Bold*
_Italic_

Table
||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|",Test,,,"My second Test Zephyr Squad

*Bold*
_Italic_
+Underline+

List
* One
* Two
* Three

Table


||Heading 1||Heading 2||
|Col A1|Col A2|
",
2,,Manual,,3,"Second step Zephyr Squad Details

[Atlassian|http://atlassian.com]","Test Data Zephyr Squad Details

[Atlassian|http://atlassian.com]","Test Result Zephyr Squad Result
",Test,,,,
3,,Manual,My first Zephyr Squad Test (Lite),3,First step of Zephyr Squad first test,Test Data of Zephyr Squad first test,Test Result of Zephyr Squad first test,Test,,,Description of the Zephyr Squad Test,
3,,Manual,,3,"Second Step of Zephyr Squad
*Bold*
_Italic_
+Underline+",Second Step Test Data,Second step test result,Test,,,,
3,,Manual,,3,"Third Step

Table

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","Third Step Test Data

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|","Third Step Test Result

||heading 1||heading 2||heading 3||
                                |col A1|col A2|col A3|
                                |col B1|col B2|col B3|",Test,,,,


The first Test corresponds to a BDD Test Case, but Zephyr Squad does not export the details of it (Scenario outline, Scenario, etc.) in the Excel file. The CSV file shows that it is just another test and will be imported as such.

The second and third Tests have one line per each step. Notice that the format is kept for the table and styles added in Zephyr Squad.


Tests of Detail and Lite types are imported the same way.

Other Tests

The script will convert all tests of type Lite and Detail, preserving the styles and formats from Zephyr Squad. 

BDD-Gherkin tests are imported without the gherkin scenarios as they are not exported into the Excel file by Zephyr Squad.



Tips

  • Use the CSV file provided to import the examples and the associated JSON configuration to correct the setup and mapping.
  • Ensure you are using the scripts available for the right version of Jira (Cloud or Server).