Migrating from TestRail to QTM4J using Migration Tool

In this guide, we will run you through the steps to migrate your data from TestRail to QTM4J. This documentation enlists all the information on migration process like what can be migrated, and what are the assets/data that may not be migrated, features of the migration utility along with System Requirements and Pre-requisites to be taken care before proceeding with migration.

What TestRail assets are migrated?

Capabilities of the Migration Tool

• Migrates Tests, Test Steps and all their fields.
• Migrates Test data in Test Steps, Test Suites, Test Runs/Executions.
• Migrates custom fields & their values for all the assets.
• Migrates folder structure. 
• Migrates Milestones child Milestone as Jira Releases.
• Migrates section as folders.
• Migrates comments for all the assets.
• Migrates linkages between assets.
• Migrates all the attachments & URL links.
• Support for Mapping of TestRail Enumerated fields and their values with QTM4J fields.

System Requirements

1. JDK 1.8.0 needs to be installed.
2. MySQL services and MYSQL workbench 5.7 or above needs to be installed.
3. Operating Systems: Windows 10, Linux - Cent OS 7, RHEL
4. CPU: 8 Cores, RAM: 16 GB
5. TestRail Professional cloud version 7.5.6, TestRail Professional server version 7.5.3.1000 (Utility is tested on)
6. Get your Migration Tool (migrate2qtm.war) and its license (qmetry-license-version-1.0) from Professional Services team.
7. Jira and TestRail should be running on your system with valid license.
8. Set UTC Time Zone in Jira as all the dates from TestRail will be migrated in to QTM4J as per UTC time zone.

Pre-requisites

1. Install Certificate in JDK on the machine running the migration utility.

   • Follow the steps specified here : How to install certificate in JDK ?

2. Remove/rename duplicate list values for system/custom fields in TestRail as QTM4J does not support creation of duplicate values.
3. All the users using TestRail should be created in Jira before the migration process starts.

4. Create a Scrum software development template project in Jira. The purpose of template project is to create a project structure that will be used to migrate the actual TestRail project with data into QTM4J.

   

Migration Steps

Run the migration utility from its dedicated machine.

• Open the command prompt and go to the migrate2qtm.war directory.
• Put license file "qmetry-license-version-1.0" besides migrate2qtm.war file.
• Run the following command by giving the path of the migrate2qtm.war file : PATH_TO_WAR_FILE>java -jar migrate2qtm.war --spring.datasource.username=<DB USERNAME> --spring.datasource.password=<DB PASSWORD>
  • cd <PATH_TO_WAR_FILE>
  • java -jar migrate2qtm.war --spring.datasource.username=<dbusername> --spring.datasource.password=<dbpwd>

The application should be accessible from the same machine using the URL : http://localhost:8080/migrate2qtm . Once you're on the source selection page of the Utility, select TestRail and proceed with steps below:

Step 1: Source Login

We recommend logging in using Admin Credentials so that the Projects available for migration are not restricted by a user's permissions.

• Base URL: TestRail URL in the format: http://<IP Address/URL> 
• Email : TestRail user's login email
• Password: TestRail user's login password
• Type: Choose TestRail instance type from dropdown: Server or Cloud

Step 2: Destination Login

Select the destination as QTM4J and move forward for login page. We recommend logging in using Admin credentials so that the projects available for migration are not restricted by a user's permissions.

a) For Jira server:

• Base URL: Your Jira server URL.
• Username: Jira username
• Password: Jira password
• QMetry API Key: Get the API from: QTM4J > Configuration > Others > Open API

b) For Jira cloud:

• Base URL: Your Jira server URL.
• Email ID: Email id used for Jira login
• API token: Get the API token from: Atlassian Account settings > Security > Create and manage API token > Create API token
• QMetry API Key: Get the API from: QTM4J > Configuration > Others > Open API  

Step 3: Pre-requisites

Make sure you comply with the pre-requisite mentioned on the screen.

Step 4: Project Selection

TestRail project and Jira template project:

• Jira template project: Select the Jira software scrum project template to be used to create the project structure. The template project should be empty.
• TestRail project: Select TestRail Project you would like to migrate into QTM4J. 
• Project key and Project Lead can be given by selecting the '' If required, Add Project Lead....." checkbox.

Step 5: Entity Mapping

TestRail → QTM4J Entity Mapping: 

Under this section, map your TestRail assets which need to be migrated into relevant QTM4J assets.

Step 6: Custom Fields

You can select system fields and user-defined fields that are part of your TestRail project that needs to be migrated to QTM4J.

Note: This is an important step to ensure there is no data loss when the project is migrated to QTM4J. Make sure all the required fields are selected correctly. Once migrated, the data cannot be reverted.

Selected fields will be converted as custom fields in QTM4J and will be auto mapped with the appropriate fields in the field mapping page.

a) Custom Field for TestRail's Testcases

b) Custom Field for TestRail's Test Suites

Step 7: Field Mapping

Field mapping helps you to map the fields of your TestRail assets to respective QTM4J fields. Complete the field mapping for all the fields to get their data migrated to QTM4J.

Note: Any mandatory field of TestRail should be mapped to mandatory field of QTM4J. The field type of the mapped fields of TestRail and QTM4J should be same.

a) Field Mapping for TestRail Test Case → QTM4J Test Case

b) Field Mapping for TestRail Test Plan → QTM4J Test Plan

c) Field Mapping for TestRail Test Run → QTM4J Test Cycle

Step 8: Field Value Mapping

You can map the values of your different enumerated fields of TestRail to that of QTM4J.

Migration Tool provides an option of "Add value" if user wants to create a new field value in QTM4J same as that of TestRail. To create the new values > Click on the checkbox beside the field value > Click on "Add value" button below > Now map the TestRail field values to the newly created QTM4J fields values.

Note: The Add Value option is not available for test execution status and test step execution status. For that you need to manually create the execution status in the template project of QTM4J before beginning the migration process.

a) Field Value Mapping for Test cases

b) Field Value Mapping for Test Cycle

Step 9. Migration

Click on the Migrate Button to start the migration process. 

The migration progress can be monitored until it is completed.

Once the migration is completed, you can log in to QTM4J and verify all the migrated data in your migrated project(s).

Post-requisite

The migration utility is designed to support resumption of the data migration from the same point in case an error is encountered due to data issues or other reasons. In such cases re-migrating the project is not necessary. At times when you run into errors, you can try to resume the migration after capturing the logs as follows.

• Capture Migration Logs

  • The logs should be present in the logs folder of the migration utility directory containing the .war file. Zip the logs folder and send it to Professional Services team for investigation.

• Resume the Migration

  • The migration can be resumed by refreshing the existing page or clicking "Resume" on the migration page.

Important Notes & Limitations

• Dashboards, To Do, Reports of Projects, Overview, Activities, Graphs, History logs will not be migrated.
• TestRail users are not migrated to Jira through migration utility. The users need to be created in Jira manually before starting the migration.
• TestRail does not provide API to get attachments directly linked to Test suite. Hence, such attachments will not migrate.
• Test Suites are migrated as folder of Testcases. Hence, all the sections and Testcases under Test suite will get migrated as Testcase folders and testcase respectively.
• Attachments greater than 25 MB(for QTM4J cloud) or 10 MB(for QTM4J server) in size are not migrated. Such attachment details will be added to the 'skipped_attachments.log' file.
• For assigning users to the migrated assets:
  • If the user is found in Jira, the entity assigned to him in TestRail, gets assigned to that user in QTM4J.
  • If the user is not found in Jira, but the selected Project Lead user is present in Jira, the assets of TestRail are assigned to that user.
  • If the user and Project Lead are not found in Jira, the assets are assigned to Jira's System Admin.
• QTM4J Testcase: Estimated time maximum value is 99:59 [HH:MM]; the value will be skipped for Estimated time > 99:59 [HH:MM].
• QTM4J server does not support shared teststeps and hence shared teststeps of TestRail cannot get migrated.
• Reference and attachments of Milestones will not get migrated as Release of Jira does not support these fields.
• Description of folder and Milestone will get migrated as plain text. Any inline image in the description will not migrate.
• Comments in TestRail supports attachments whereas QTM4J comments does not. Hence, attachments of comments will not migrate.
• If result of execution has only Assignee and not the execution status update, then it will not migrate.
• Created by, Updated by and Executed by fields are non updatable in QTM4J and hence will have the name of user conducting the migration process.
• Temporarily deleted testcase will not get migrated until they are restored before starting the migration process.
• Attachments for sections and sub-sections will not be migrated.

Need Assistance?

If you run into any questions or concerns during your migration, you can reach out to Professional Services by raising a ticket directly on our Support Portal. We would be happy to assist you!