Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

You can use the Xray's Test Case Importer to import Tests new or existent tests, preconditions and test sets issues from a CSV or JSON source file. 

...

  • preparing data (CSV/JSON) beforehand
  • submit the data 
  • choose the destination project along with some global settings
  • for CSV, define the mapping of CSV columns <=> fields in Jira 

...


Info
titlePlease noteSupported issue types

The Test Case Importer is only able to create Test or update tests, preconditions and test set issues. If you wish to create or update other types of issues, you should use Jira's CSV importer instead. Note that Jira's CSV importer is not able to handle any Xray related semantics though.


Table of Contents
maxLevel3


Note
iconfalse
titleSee and try some examples by yourself
typeInfo

Please see a tutorial with working Examples using Test Case Importer, showcasing different scenarios, which you can download and try by yourself.

Accessing the Test Case Importer

Xray provides the ability to import multiple Tests, Preconditions or Test Sets at once either as a standard user or as a Jira administrator; the user can create or update all those issues types with a maximum number limit of 1000 issues per import.


Info
titlePermissions

Only users that have the Make Bulk Changes permission will have this option available. The configuration can be found in the Jira Administration / System.

Additionally, the user will only be able to import data into projects where he has the Create Issues permission. This configuration can be found in the Jira Projects / Project Settings / Permissions.

From the top Apps menu

Go to Apps > Xray. In the "Xray" side menu, select "Test Case Importer" and then select the format you want to use (e.g. CSV).

Image Added
Image Added

From within Testing Board in a project

The Test Case Importer is also accessible from within the Testing Board of a Xray-enabled project.

Image Added

Info
titleIf you have the old Jira UI

Image Added                     Image Added


Importing data 

CSV Importing

Downloadable examples

Please check multiple examples in the tutorial Examples using Test Case Importer (as well as code in GitHub).

Preparing the source file

...

You can name the fields as you wish since they are going to be mapped during the importation process, but there are three mandatory fields that must be mapped:

  1. Test ID – this is the field used to identify which lines belongs to which test caseIssue Id – a unique identifier for the issue, this field is used to group lines that belong to the same test case or to identify a precondition or a test set.
  2. Summary – this field is mandatory since Jira doesn’t allow you to create an issue without a summary.
  3. Test Type – this field defines the Test test type of the each test to import. The Test Type test type must match one of the types of the project to which the test is being imported.

Here is an example of a source file as seen in a spreadsheet application:

Image RemovedImage Added

Here is the same example as seen in a text editor:

Image RemovedImage Added

Info
titleImporting into multiple projects

The tests issues can all be imported to the same project or into multiple projects, one column in the source file can be used to define the destination project (either by having its key or id).

...

Info
titleFields with line breaks

If you need to use new lines within a field, for example, in the issue description, then you need to quote the field.

Importing

...

Info
title<<!clear!>> special marker

The <<!clear!>> special marker removes the values of the field (with the exception of test step fields) where is it specified (only applicable as a valid input of a csv file).

Open Test Case Importer

Open Test Case Importer and select CSV format.

Image Removed                     Image Removed

File Import step

Provide the source file and settings regarding the file to import.

...

  • An existing configuration file saved from the last import made with this file or a similar one.
  • The file encoding used in the CSV source file, ; this is especially important when the file contains non-ASCII characters. The supported encodings can be seen here.
  • The CSV delimiter is the column delimiter used used.

Setup step

Aditional Additional setup information, for choosing the destination project along some settings related with the source data.

...

During this step, you'll define the mapping of columns to Jira/Xray fields.

There are two three mandatory fields that must be mapped: Test ID, Summary and Test Type.

Besides these ones, if you have defined additional fields as mandatory for Test issues, then you will also need to specify their mapping.

Image RemovedImage Added

Project field

The project to which the test will be imported can be defined for each test issue in a field. The fields "Project Key" or "Project Id" can be used for this.

If no project field is mapped or when the value in this field is empty, the project selected in the Setup step will be the one where these tests issues will be imported into.

Issue Key field

To update existing issues, your CSV file needs to contain a column that maps to Issue Key. If an issue exists for a given key, it will be updated.

Image Added

Issue Type field

The type of the issue being imported. The supported issue types are:

  • Test ("test" case insensitive)
  • Precondition ("precondition" case insensitive)
  • Test set ("testset", "test_set" or "test set" case insensitive)

If no issue type is defined for an issue being imported, it will default to test. When updating issues, the field can be left empty on the csv file.

Image Added

Test Type field

The type of the Test being imported. Must be filled for a Test in your CSV file, when creating one, and can be left empty when updating an existing Test.

Image Added

Precondition Type field

The type of the Precondition being imported. Must be filled for a Precondition in your CSV file, when creating one, and can be left empty when updating an existing Precondition.

Image Added

Precondition Specification field

The "Steps", "Definition" or "Background" of a manual, generic or cucumber Precondition type, respectively.

Image Added

Preconditions field

Only for test issues, a list of preconditions to which a test will be added.

Each value should be the issue key of an existing precondition or the id of a precondition also being imported ("Test ID" field).

Image Added

Test Sets field

Only for test issues, a list of test sets to which a test will be added.

Each value should be the issue key of an existing test set or the id of a test set also being imported ("Test ID" field).

Image Added

Test Repository Folder field

The Test Repository folder path to the folder in which the Tests will be associated.

...

Links can be created between imported tests and other existent issues using the "Link ..." Jira fields. Only applicable when creating an test.

The field is a list field and the value of the respective field should hold a list the issue keys of the issues to link to the test.

...

You can also map columns to test step fields for manual tests.
The fields are in the group "Xray Test Step Fields".

The configured test step fields for every project in the instance is shown here and the ones that are required are shown with a "*".

Unstructured Definition field

The "Definiton" of a generic Test type.

Image Added

Gherkin Definition field

The "Scenario/Scenario Outline" of a cucumber Test type.

Image Added

After this step the import process will start.

...

The JSON source file must have the same structure as the one used in the import through the REST API.

Example of one test being create and one existent test being updated in the JSON import format:

Image RemovedImage Added 

Importing

Image Added


Example of one Test Set being created and one existent Test Set being updated in the JSON import format:

Image Added

Example of one Precondition being created and one existent Precondition being updated in the JSON import format:

Image Added

Open Test Case Importer

Open Test Case Importer and choose the JSON file formatTo import tests using a JSON source file, you must choose the JSON file format in the Test Case Importer.

File Import step

Choosing Choose the file having the source data to import from.

Image RemovedImage Added

Setup step

Choosing the default project to import into. If each test to import already refers to a project, this field is not necessary to be filled, otherwise you should choose a project.

Image Removed

Results of the import process

...

Example of 5 tests imported successfully:

Image RemovedImage Added

You may also download the detailed import results, this is useful to get the issue keys of the imported test issues and also to see which tests issues were not imported and why.

Example of 4 tests 2 issues imported out of 5:

Image RemovedImage Added

Detailed import result for the example aboveExample of detailed import results:

Image RemovedImage Added

In the detailed import resultresults, the elementNumber field represents to which test issue the information corresponds to (elementNumber 0 being the first testissue).

When importing tests into Test Repository folders, if for any reason the process is unable to create a folder or move a test to the respective folder, the respective tests will be still be migrated and a warning detailing the situation will be written to the import result.

...

When importing a file, when the import status is being shown, you can download the configuration file that will have all the settings you've set:

Image RemovedImage Added

And then you can use it when you import the next file (if the configurations are supposed to be the same or similar):


Examples

Please see a tutorial with working Examples using Test Case Importer, showcasing different scenarios, which you can download and try by yourself.