Blog / Software Testing


Xray v2.1 – Import Manual Tests with Test Case Importer

Test Case Importer for Manual Tests

Xray v2.1 is almost here and it brings some excellent news concerning importing manual tests.

Until, and including, Xray v2.0 it was possible to import Tests, either Manual or other, using JIRA’s native CSV importer plugin (JIM) available under JIRA’s administration in System => External System Import.

Although it worked just fine, since the CSV mechanism from JIRA is generic, it would require some preliminary work in order to build a CSV file with the proper layout, namely for manual Tests. The problem with manual Tests is that they may have multiple steps, and you need to include them on the “Manual Test Steps” custom field which expects a JSON structure.

So, in general, you had to:

  1. create a friendly CSV with your manual Test steps
  2. convert them to the CSV understood by JIRA’s CSV import plugin, using an external tool named “xray-converter”
  3. finally, import them with JIM

Now, with this new feature you can import manual Tests from a human readable CSV source file through the specific Xray Test Case Importer, which basicaly avoids the second step mentioned above and the need to use a local tool in your computer.

With the Test Case Importer you just need the CSV containing the manual test steps and your JIRA instance with Xray.

Importing Test Cases

Preparing the CSV for importing

You can easily write the manual Tests in Excel, LibreOffice or any other tool capable of exporting rows/columns to CSV.

There are 3 mandatory fields you need to specify, although you can name the fields as you wish since they are going to be mapped during the importation process.

  1. Test Case Identifier – this is the field used to identify which lines belong to which test case. In the example bellow, it is the ‘TCID’ column. All the rows corresponding to steps of the same Test should have the same Test Case Identifier.
  2. Summary – this field is mandatory since JIRA doesn’t allow to create an issue without a summary. In the example bellow, it is the ‘Test Summary’ column.
  3. Step – this field is going to be mapped as the ‘Step’ field of a Manual Test step. In the example bellow, it is the ‘Step’ column.

test case structure
Example of a sheet with two manual Tests

Whenever exporting to CSV, please use a proper delimiter (“;” or “,” are good candidates) and remember the encoding being used to save the data. In the following example, “;” was used as delimiter.

test case strucutre CV
How the CSV file looks like once the test cases above are exported


In order to start the importation process, you’ll need to:

  1. Log in with an administrator account;
  2. Go to Projects>Import External Projects;
  3. Choose the “Xray Test Case Importer” like shown in the image bellow:

steps test case importing

Next, you need to setup the basic settings:

test case setup


  • CSV Delimiter field is where you provide the column delimiter used in your CSV source file.
  • File Encoding field is where you provide the encoding used in your CSV source file. Make sure that you provide the right encoding.

Optionally, you can use settings saved from a previous importation.

Next, you need to map the fields from your CSV to JIRA and Xray fields:
test case FIELDS

Note that it’s mandatory to map at least three fields.

  1. Test Case Identifier (located under Manual Test Step fields). In this example this field is mapped with the TCID column from the CSV file.
  2. Summary (Located under JIRA fields) In this example this field is mapped with the Test Summary column from the CSV file.
  3. Step (located under Manual Test Step fields) In this example this field is mapped with the Step column from the CSV file.

You can also Map the CSV column values, in case you need it.

The fields that aren’t mapped will not be imported within the test case.

Next, select the Xray project where you want your Manual Test cases to be imported:
test case maps projects

After this last step, Xray Test Case Importer will import the manual test cases to the selected project. For last, a configuration file can be saved to import other manual Test cases afterwards using the same configuration.

Xray Test Case Importer vs JIRA’s native CSV importer


The native JIRA CSV importer can still be used to import Tests, manual (with the limitations mentioned above) and non-manual Tests. It can also be used to import other issues, such as Pre-Conditions, Test Sets, Test Executions and Test Plans.

Therefore, the two mechanisms complement each other, although the recommended way for importing Manual Tests is using the Test Case Importer due to its simplicity.

In the future…

We do intend to extend the capabilities of Xray’s specific “Test Case Importer” to be able to import other types of tests, namely Cucumber Scenarios/Scenario Outlines. Stay tuned!

Read more about it in our documentation

We hope you are able to easily migrate your existing Test cases so you can take advantage of Xray for JIRA as soon as possible!



    • Hi Adelaj,
      We are at the latest QA phase of the release so, Xray’s 2.1 version should be out by the end of next week, until 24th March.
      Please keep an eye on our Blog and Twitter to get all the latest news about our releases.
      Xpand Add-ons team

  • Please, include trial version Xray also Test Case Importer?
    I wanted to test the import csv files into JIRA v6.0.4, but Xray is not in menu: External System Import – Import external projects 🙁

    • Hi Kamila,

      Thank you for your comment!
      The Test Case Importer is also available in the trial version. You can read more about it here.

      If you still need any assistance please open a ticket here.
      Our technical team will be glad to help you.

      Best regards,
      Xray Team

  • Hello, thank you for the explanation on the process how to import Tests by using Test Case importer.
    Let’s assume that you have already uploaded your Test cases as Tests and also assigned them to folders in Test Repository.
    During testing it will turn out, that many TC’s are wrong, so they need to be changed.
    You will again use the excel modification of the TC’s for easier/bulk changes for upload.
    However during upload new Tests are created, i.e. the original TC is not overwritten and there is no versioning.
    How is it possible with the Test Case importer function to achieve updating existing JIRA Test, rather then creating a new one?

    • Hi Stefan,

      Xray’s Test Case Importer (a Jira Importer Plugin extension) its an importer of Manual Tests from a CSV source file. The Test Case Importer is only able to create Test issues and it was created by Xray. 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.

      Furthermore, Test Case importer only creates tests, with Jira’s native importer you can create and update tests, as well as using our REST API.

      Best regards,
      Xray Team

  • Hi,

    I want to import 3000 Test Cases. I will use the CSV files to import those test cases. I want to map test cases with Test sets when I do the import. Can I do it? If yes, can you please share the process for it.


    • Hi Jay,

      Yes, that is possible. On the screen where the user is able to map the values he has on the CSV with the Jira/Xray Custom fields, the user has to map the Test Set key value to the Custom Field: Test Sets association with a Test.
      You may find on our documentation how to use the Xray Test Case Importer, here.

      Best Regards,
      Xray Team

Leave a reply