This tool is deprecated and is going to be removed on future versions.

From Xray 2.1 onwards, the preferred way for importing Manual Tests is by using Xray's Test Case Importer, as detailed in Importing Manual Tests using Test Case Importer.

 

Some users consider easier to create Manual Test definitions in a spreadsheet and then import them to Xray using the import procedure described in Importing and Exporting Tests (CSV). Xray for JIRA provides a tool xray-converter to make it straightforward.

This tool converts a CSV, that basically contains the steps definitions, to the generic JIRA's CSV compatible import format, which requires all rows to be fulfilled. 

 

Conversion overview

  1. Your step definitions must be defined in a spreadsheet that follows a specific format (see bellow). So, you can either use an example file as basis, or adapt your already existing spreadsheet;
  2. Then, you may run xray-converter to convert the steps "spreadsheet" to the generic CSV format supported by JIRA/Xray.;
  3. Don't forget that in the end you will have to import the tests, using the newly created CSV file, as described in Importing and Exporting Tests (CSV).

Layout of spreadsheet with steps

Your spreadsheet must obey this format (example file):

TCIDProjectRegionIssue_TypeEnvironmentSummaryComponentDescriptionReporterPriorityLabelsTest_TypeStepDataExpected_Result
1QA Test RepositoryAMERTestTestTest Case 1App1Test Description 1Ivaan, Iftekhar: IT (NYK)TrivialJava,TestManualBrowse to urlwww.bn.comBN home page shows
1           Clicl login  
1           Enter Useridiivaan 
1           Enter Passwordxyz123OK button enable
1           Click OK Welcome Msg shows
2QA Test RepositoryAMERTestTestTest Case 2App1Test Description 2Ivaan, Iftekhar: IT (NYK)TrivialJava,TestManualBrowse to urlwww.bn.comBN home page shows
2           Click OK Welcome Msg shows
3QA Test RepositoryAMERTestTestTest Case 3App1,App2Test Description 3Ivaan, Iftekhar: IT (NYK)TrivialJava,TestManualBrowse to urlwww.bn.comBN home page shows

The TCID must be the first column of your spreadsheet and the Step, Data and Expected_Result the last three columns. These columns are mandatory, otherwise the conversion won't work properly.

Is also advised to always have the Issue_Type and the Test_Type columns in order to force JIRA to create your tests with the correct Issue Type and Test Type.

Export steps spreadsheet to CSV

Export your "steps spreadsheet" to CSV and set your separator type as ; preferably. You'll now have a file similar to the following output (example file).

TCID;Project;Region;Issue_Type;Environment;Summary;Component;Description;Reporter;Priority;Labels;Test_Type;Step;Data;Expected_Result
1;QA Test Repository;AMER;Test;Test;Test Case 1;App1;Test Description 1;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows
1;;;;;;;;;;;;Clicl login;;
1;;;;;;;;;;;;Enter Userid;iivaan;
1;;;;;;;;;;;;Enter Password;xyz123;OK button enable
1;;;;;;;;;;;;Click OK;;Welcome Msg shows
2;QA Test Repository;AMER;Test;Test;Test Case 2;App1;Test Description 2;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows
2;;;;;;;;;;;;Click OK;;Welcome Msg shows
3;QA Test Repository;AMER;Test;Test;Test Case 3;App1,App2;Test Description 3;Ivaan, Iftekhar: IT (NYK);Trivial;Java,Test;Manual;Browse to url;www.bn.com;BN home page shows

Make sure you have Java environment installed on you machine and set JAVA_HOME. You can follow these instructions https://confluence.atlassian.com/display/CROWD/Setting+JAVA_HOME

Running

  1. Copy the CSV with the steps to the data/ subdirectory within the xray-converter folder

  2. Run xray-converter (see syntax bellow)
  3. Import the issues to JIRA using JIRA's native CSV import feature

 

In Unix based systems or OS X you must use the xray-convert.sh executable; in Windows you should use the xray-converter.bat batch file.

Syntax

ArgumentDescriptionExample (based on spreadsheet example)
-pathThe path to the file to convert-path ./data/SampleTestCase.csv
-dataThe test step's Data column name-data Data
-resultThe test step's Expected Result column name-result Expected_Result
-stepThe test step's Step column name-step Step
-attrDelimiterThe delimiter used in the file to separate the different attributes-attrDelimiter ";"
-testDelimiterThe delimiter used in the file to separate the different tests to import, else please provide the column name. When this cell value changes, it means that the line represents a new Test-testDelimiter TCID

Examples

Unix

./xray-converter.sh -path ./data/SampleTestCase1.csv  -step Step -data Data -result Expected_Result -attrDelimiter ";" -testDelimiter TCID

Windows

xray-converter.bat .\data\SampleTestCase.csv Step Data Expected_Result ";" TCID

When executing the xray-converter.bat file, you do not specify the argument's names but you must respect the order shown in the example

When exporting from XLS to CSV, choose the option: "CSV (comma separated)" ;

The test steps to import in the XLS, can not contain the caracter " at the end of any line, otherwise the exported document will be unformatted;

If you get an error like

'C:\Program' is not recognized as an internal or external command,
operable program or batch file.

it's because Windows is not interpreting JAVA path as it should.

E.g:

ECHO %JAVA_HOME%
C:\Program Files\Java\jdk1.8.0_45

You can fixed it with providing JAVA_HOME path with a "" e.g. "C:\Program Files\Java\jdk1.8.0_45" or more radically, copy this folder to C:\jdk1.8.0_45 and change JAVA_HOME to C:\jdk1.8.0_45

Installing

  1. Download xray-converter here
  2. Unzip it to a directory of your choice

New version. Compatible with newlines inside cells ("\n", "\r").