You can use the Xray's Test Case Importer (a Jira Importer Plugin extension) to import Manual Tests from a CSV source file.
Before importing
The CSV source file must follow some simple rules.
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:
- Test Case Identifier – this is the field used to identify which lines belongs to which test case. In the example below, it is the TCID column.
- Summary – this field is mandatory since Jira doesn’t allow you to create an issue without a summary. In the example below, it is the Test Summary column.
- Action – this field is mapped as the Step field of a Manual Test Step. In the example below, it is the Action column.
Here is an example of test cases structure:
This is how the CSV file looks like once the test cases above are exported (download it from the downloadable examples section):
CSV column separator
If you choose the “,” (comma) as the CSV column separator, then you must use quotation marks around any field that contains commas.
Fields with line breaks
If you need to use newlines within a field, for example, in the issue description, then you need to quote the field.
Xray issue types and respective screens
Please make sure your project has Xray's "Test" issue type and its associated screens are configured properly. This is done automatically if you followed the Quick Setup instructions.
If you added Xray's issue types by hand to your project or if you changed the screens/screen scheme configurations, then you may need to perform additional configuration operations.
More info on Custom Fields and Screen Configuration and Configuring Xray with an Existing Project
Downloadable examples
Please check multiple examples in the tutorial Examples using Test Case Importer (as well as code in GitHub).
Importing Test Cases
Xray provides the ability to import multiple test cases at once either as a standard user or as a JIRA administrator; there is no limit on the number of tests that can be imported.
As a JIRA Administrator
For demonstration purposes, the CSV example file from the previous section is used.
To complete the importation process, follow the steps below.
- Log in with an administrator account.
- Go to System > Import and Export > External System Import.
- Select the Xray Test Case Importer.
- Follow the Setup Page section instructions
As a Non-Administrator JIRA user
- Log in with a non-administrator account.
- Got to Tests menu > Test Case Importer as shown in the image
- Select the Test Case Importer menu item
- Follow the Setup Page section instructions
Permissions
Only users that have the Bulk Change 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.
Setup Page
Provide the basic settings for the importation process.
- The CSV Delimiter field is the column delimiter used in your CSV source file.
- 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.
- Optionally, you can use the settings from a previous importation.
Project Page
- Select the Xray project where you want your Manual Test cases to be imported.
- Set the Date formats that will be used for all Jira custom fields and also to the Manual Test Step Custom fields of type "Date picker" and "DateTime picker".
Check the Hierarchical Test Organization - Create Folders option to allow mapping the imported Manual Test cases Test Repository Path on the Field Mapping Page
Field Mapping Page
Map the fields from your CSV to Jira and Xray fields
It is mandatory to map at least three fields:
- Test Case Identifier (located under Manual Test Step fields). In this example, this field is mapped to the TCID column from the CSV file.
- Summary (Located under Jira fields) In this example, this field is mapped to the Test Summary column from the CSV file.
- Action (located under Manual Test Step fields) In this example this field is mapped to the Action column from the CSV file.
The fields that are not mapped will not be imported to the test case.
Custom field mapping
Only custom fields that have the issue type Test selected as one of the applicable issue types will be available for mapping.
Available custom fields for import:
- Checkboxes
- Labels
- Number fields
- Radio buttons
- Select lists (single choice and cascading)
- Text field
- URL field
- User picker
Note: Only "single-value" custom fields are supported. "Select List (cascading)" custom fields behave as a single-value field; in that case, you have to specify the value in the format "parent -> child" as mentioned also for Jira's native CSV importer.
Value Mapping Page
Map the CSV column values. In the example above, the Map Field Value checkbox is selected for Priority, so those values are going to be mapped.
Now just click Begin Import and Xray Test Case Importer will import the manual test cases to the selected project.
The importation process is complete. A configuration file can be saved to import other manual test cases in the future.
Special fields
Attachments
It is possible to attach files to Test and to Test Steps.
Attachments
The attachment may be referred by name (in this case the file:// protocol is assumed), by "file://" or "http(s)://". Multiple files may be specified within one CSV column; for this, the attachments must be delimited by space.
Note: For file protocol, only files in the "<JIRA_DATA_HOME>/import/attachments" folder will be imported.
Test Repository folder
If you want to add the Tests to some folder within the Test Repository, you can specify a column having the Test Repository Path.
Folders and their respective sub-folders must be delimited by "/", as shown in the following example:
To create new folders and sub-folders, in case they do not exist in the Test Repository, or map the imported Manual tests to folders and sub-folders that already exist in the Test Repository, you must select the option 'Create Folders' in the Setup page of the Test Case importer.
Please note
To have this option available, you must be able to, at least, access the target project (i.e., browse permission), the Hierarchical Test Organization must be enabled in Xray settings, and:
- have one of the project roles configured on the default Xray global permission for the Hierarchical Test Organization in Xray settings.
Or
- have the Create folders and Move issues user Xray Test Repository Permissions configured on the Project Permission Scheme of the target project
With the 'Create Folders' in the Setup page of the Test Case importer, on Field Mapping page, during the mapping step, you need to map the CSV column containing the path to the "Test Repository Path" Xray's custom field.
Please note
The "Test Repository Path" is case insensitive and each folder is trimmed (spaces are removed from the start/end of it).
This means that "components/compA", "components /compA", and " components/COMPA" are all the same and will be mapped to the same folder within the Test Repository.
If the folder is not found, then the Test is created, but it is not associated with any folder; it will appear in the "Orphans" meta-folder. Unless you selected the option 'Create Folders', in the Setup page.
Links
You can import a link to other issues for newly-created Tests by choosing the "Link ..." mapping.
Links to requirements
When importing Tests, you can specify the links to the requirements that each Test validates. For that purpose, 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.
Date Time fields
Dates and Date Time field formats must comply with the Java SimpleDateFormat. On the project mapping page, the format used on the CSV file should be given in order for the import process to complete without errors or warnings.
Example of valid SimpleDateTime formats
- dd/MM/yyyy hh:mm
- dd/MMM/yy h:mm a
Comments
Comments can be added to Test issues using the "DateTime;User;CommentBody" syntax, where DateTime and User are optional.
More that one comment can be added for each issue, by adding more than one column on the CSV file.
DateTime uses the Date Time format specified on the project mapping page, and User must be a valid username.
Example valid comment entries
- 01/01/2012 10:10;Admin; This comment works
- 01/01/2012 10:10; This comment also works
- "This comment is only the text body"
Priorities
An issue's priority defines its importance in relation to other issues. You can read more here. Before Jira 7.6, priorities could only be defined globally (i.e, for all projects). In Jira 7.6, Jira allowed a Project to have custom Priority Scheme. When using Jira CSV importer, Jira has different behaviors when Priorities are provided or not, depending on the Jira versions.
Xray will have the same behavior, no matter what version of Jira. When a user (admin or not) is trying to import a CSV with Xray Test Case Importer:
- Priority is provided and is associated with Project: Xray will create the Tests with the priority provided in CSV
- Priority is provided but does not exist or is not associated with Project Scheme: Xray will create Tests with the default priority if set, or with the lowest ranked priority;
- Priority is not provided: Xray will create Tests with the default priority if set, or with the lowest ranked priority;
Issue Key (Update Existing Manual Test)
As in Jira's native CSV import, we provide means to updating an existing issue.
In order to Update an issue you must comply with the following pre-conditions:
- Issue keys must belong to the same project as mapped in the "Import to Project" option.
- Issue keys must belong to an existing editable Issue, of type "Test" and with a "Manual" Test Type.
- User must have Create and Edit permission for all Issues being updated.
While updating the Manual Test Issues, keep in mind that your Manual Test Steps will be overwritten with the new Step specification declared in the CSV file.
Update Issue Field Behaviour
- Manual Test Steps will be overwritten with the new Step specification as declared in the CSV file (including any Test Step custom fields)
- All other issue Native and Custom Fields for the issue, will be updated according to the same rules applied in the Jira's native CSV importer.
Useful tips for importing Tests
Importing data in any system is a non-linear process; you may need to run it multiple times until you get the expected result because it is easy to forget to map a field or use a delimiter, etc.
- Add a unique label to all your tests, so you can clearly identify the tests imported at a given time. This will make analysis simpler and performing bulk operations (e.g., change fields, remove fields) will also be easier.
- Use a custom field for storing the external ID of the tests in their original system. Thus, whenever tests are imported, you can easily compare them with the original tests in the original system.
Examples
Please see a tutorial with working Examples using Test Case Importer, showcasing different scenarios, which you can download and try by yourself.