Do you want to migrate tests from other tools? If you are able to export them to a Excel/CSV file, then you may import the tests to Jira using also using the instructions bellow. If you need guidance on a specific use case, please contact us. |
You can import Test definitions from external sources using CSV files, either by using Xray's Test Case importer (recommended) or Jira's native CSV importer plugin (see Importing Data from CSV).
This page explaing the later procedure, which is more generic and supports importing of all Test types. However, for manual Tests you should use Xray's Test Case importer.
To import issues using Jira's CSV importer, as an administrator, you have to:
As a standard user, you can also import issues:
Aside from the native issue columns like Summary and Description, you need to specify in the CSV file additional columns related to Xray Test issues.
There are some columns that you also need to specify, depending on the type of Test as described in the next sections.
When importing Tests, you can specify the links to the requirements that each Test validates. For that purpose, the columns must be mapped as Link "Tests". If the Test covers multiple requirements, then multiple CSV columns must be used, each one being mapped in the same way. |
If you need to import Manual Tests, you should use Xray's Test Case importer instead since it supports a more user-friendly CSV file layout for describing Test steps. |
Please be aware that it may be necessary to update |
In order to import Manual Tests in a CSV file to Jira, you need define the following columns:
[ { "index": 0, "step": "Step 1", "data": "input Data 1", "result": "Excepted result 1" }, { "index": 1, "step": "Step 2", "data": "input Data 2", "result": "Excepted result 2" }, { "index": 2, "step": "Step 3", "data": "input Data 3", "result": "Excepted result 3" }, { "index": 3, "step": "Step 4", "data": "input Data 4", "result": "Excepted result 4" } ] |
Summary; Assignee; Reporter; Issue Type; Description; Test Type; Manual Test Steps "Test issue 1"; admin; admin; 10000; "This is a Test issue"; "Manual"; "[ { ""index"": 0, ""step"": ""Step 1"", ""data"": ""input Data 1"", ""result"": ""Excepted result 1"" }, { ""index"": 1, ""step"": ""Step 2"", ""data"": ""input Data 2"", ""result"": ""Excepted result 2"" } ]" "Test issue 2"; admin; admin; 10000; "This is a Test issue"; "Manual"; "[ { ""index"": 0, ""step"": ""Step 1"", ""data"": ""input Data 1"", ""result"": ""Excepted result 1"" } ]" |
Some organizations already have Manual Test definitions in spreadsheets. These spreadsheets normally define all Tests to execute and within each Test, their steps. This is the main reason why Xray's Test Case importer is a better alternative for importing Manual Tests. Before Xray for Jira 2.1, you could use a special converter tool (now deprecated) for converting these spreadsheet Test definitions, more specifically the Test Steps, into the JSON format above expected by Xray and Jira. |
For Cucumber Test issues, you need to define the following columns in your CSV:
For automated generic Test issues, you need to define the following columns in your CSV:
Exporting tests can be done in different ways: either by using some of Jira's built-in features (which vary from Jira version to Jira version) or by using Xporter app. What you can do with Jira out-of-the-box may be rather limited but it may be enough to address your needs. If you want to have full control over the layout and the format of the generated document, then Xporter is the way to go.
Jira lets you export your data in CSV or Excel (file is saved as XLS, but you can open it with your spreadsheet tool and export it to CSV). Xray custom fields are compatible with this function. Even Manual Test Steps field can be exported in a JSON format so that it can be imported back to Jira directly.
Since Jira 7.2, Jira only provided the ability to export issues to CSV in a limited way; recent versions do not support natively the ability of exporting to Excel. If you need to export issues, including your Tests, to Excel or fully customizable templates, then we recommend you use the Xporter app. |
Recent versions of Jira give the ability to export issues, including Xray Tests, to a printable, non-customizable, layout.
You just need to go to Issues > Search, select the Test issues and the column "Manual Test Steps (Export)", if you're aiming to export manual test cases.
Then you can "export" them to a printable, non-customizable, layout, by clicking on Export > Printable.
Which will generate something like...
Then the browser can be used to print this to paper or, eventually, to PDF (if the browser supports this natively or if there is a custom printer driver for this purpose).
If you want to export to CSV to have an Excel like sheet, with the steps in a readable way, exporting to CSV using Jira will not provide you that ability (Xporter would be the proper solution). You could export the steps by including the "Manual Test Steps (export)" column but it would generate the steps as an HTML table, which Excel does not format correctly out-of-the-box.
If you want to export the Test definition (Test's description and manual test steps) in order to import them once again, you may use the following approach.
Go to Issues > Search, select the Test issues and the column "Manual Test Steps"; that column has the steps all in a JSON structure.
By using Xporter app, you can fully customize the layout of the document containing the specification of your test cases. It also gives the ability to either generate documments in .pdf, .docx or even .xlsx and .csv formats.
You can use some of the already available and free Xporter templates as basis, by downloading them, customize to your needs and upload to your Jira instance. These templates can be found in Xporter's Template Store, under "Tests & QA" section.
Some good examples for making a document related with test specification are the "Xray Test Set" and the "Xray Test Report" templates. There are some other ones, more related with execution, such as "Xray Offline Test Report" (if you're interested on this topic, please check out this blog post).
Since Xray uses Jira issue types for its core entities, it's also possible to import other entities such as Pre-Condtions, Test Sets, Sub Test Executions, Test Executions and Test Plans.
In the following examples, the Issue Type can either be specified as a string with the name of the Issue Type or with the corresponding id that can be found within "Issue Types" JIRA administration section.
You can specify the Tests by using the Tests association with a Pre-Condition mapping upon importing. Use the comma (",") delimiter to specify multiple tests.
Summary; Assignee; Reporter; Issue Type; Type; Condition; Description; Tests associated with Pre Condition "Standalone PreCondition"; admin; admin; 10; Manual; "calculator must be turned on"; "This is a PreConditon issue"; "PreCondition linked to 2 Tests"; admin; admin; 10; Manual; "calculator must be scientific"; "This is a PreConditon issue"; CALC-779,CALC-756 "PreCondition linked to 1 Test"; admin; admin; 10; Manual; "calculator must be normal"; "This is a PreConditon issue"; CALC-779 |
You can specify the Tests by using the Tests associated with Test Set mapping upon importing. Use the comma (",") delimiter to specify multiple tests.
Summary; Assignee; Reporter; Issue Type; Description; Tests associated with Test Set "Test Set without Tests"; admin; admin; 8; "This is a Test Set issue"; "Test Set with 2 Tests"; admin; admin; 8; "This is a Test Set issue"; CALC-908,CALC-887 |
You can specify the Tests by using the Tests association with Test Execution mapping upon importing. Use the comma (",") delimiter to specify multiple tests.
Fix Version; Summary; Assignee; Reporter; Issue Type; Description; Test Environments; Tests associated with Test Execution "3.0"; "Test Execution without Tests"; admin; admin; 9; "This is a Test Execution issue";; "3.0"; "Test Execution with 2 Tests"; admin; admin; 9; "This is a Test Execution issue"; Android; CALC-908,CALC-887 |
Sub Test Executions are sub-tasks of "requirements" (e.g. Story, Epic, other). Thus, the parent issue key must be provided; Jira's CSV also requires that an empty column mapped to the "Issue Id" to be passed in this case.
You can specify the Tests by using the Tests association with Test Execution mapping upon importing. Use the comma (",") delimiter to specify multiple tests.
Issue Id; Fix Version; Summary; Assignee; Reporter; Issue Type ; Parent issue (requirement); Description; Test Environments; Tests associated with Test Execution ;"3.0"; "Sub Test Execution with 1 Test"; admin; admin; 10101; CALC-2541; "This is a very simple Sub Test Execution issue"; Android; CALC-908 ;"3.0"; "Sub Test Execution with 2 Tests"; admin; admin; Sub Test Execution; CALC-2541; "This is a Sub Test Execution issue"; Android; CALC-908,CALC-2542 |
You can specify the Tests by using the Tests associated with Test Plan mapping upon importing. Use the comma (",") delimiter to specify multiple tests.
Fix Version; Summary; Assignee; Reporter; Issue Type; Description; Tests associated with Test Plan "3.0"; "Test Plan without Tests"; admin; admin; 10; "This is a Test Plan issue"; "3.0"; "Test Plan with 2 Tests"; admin; admin; 10; "This is a Test Plan issue"; CALC-908,CALC-887 |
Sometimes, you may want to copy Tests specified in some other Jira server, such as a staging or testing environment.
If you need to "migrate" (i.e., copy) the Tests to another Jira server, you may follow the instructions above for exporting Tests to CSV and to import them from CSV.
The general procedure would be:
What you will be able to copy:
What you won't be able to copy:
This procedure allows you to migrate the essential Test specifications. If you need to migrate test runs and other information, then this procedure is not applicable. You may use the REST API, but it will require some work from your side since there is no direct way to migrate it. |
Although Xray allows you to import execution-related information, Xray does not currently provide an out-of-the-box solution for migrating execution-related information along with the corresponding tests from other systems.
This approach requires some development effort from your side. |
2. Migrate organization (optional, not really necessary)
This depends on the legacy system organization. If it somehow groups tests, then use the Jira REST API to create the Test Set issues. After that, use Xray’s REST API to add the Tests. You must know the Tests issue keys in advance. On the other hand, in case you're using folders as means to organize Tests both in the original system and also in Xray, you may simply specify the folder as being mapped to the "Test Repository Path" Xray's custom field during the Test Case Importer's import process.
3. Import results
a) Create Test Executions with their respective Tests
Use the Jira REST API can be used to create the Test Execution issue. After that, use Xray’s REST API (i.e., POST /rest/raven/1.0/api/testexec/{testExecKey}/test) to add the Tests. You must know the Tests issue keys in advance.
b) Import results for each Test Execution
Each approach can be achieved using the REST API, and the POST /rest/raven/1.0/import/execution endpoint. You just need to know in advance the Test Execution key and also the issues keys for each Test that is part of the Test Execution.