Migrating from qTest to QMetry using QMetry Migration Tool

In this guide, we will run you through the steps to migrate your data from qTest to QMetry Test Management. This documentation lists 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 Prerequisites to be taken care before proceeding with migration.

What qTest assets are migrated?

1. Test Plan

qTest

QMetry

Release

Release

Build

Cycle

2. Requirements

qTest

QMetry

Notes

Module

Requirement Folder

Folder hierarchy is preserved

Requirement

Requirement

Placed in the corresponding folder

Retained: Release/Build–Requirement associations

3. Test Cases

qTest

QMetry

Notes

Module

Test Case Folder

Test Case

Test Case

Versions are carried over

Versions migrated:

  • All approved versions

  • The latest unapproved version

Retained: Test Case–Requirement links

4. Test Suites

qTest

Condition

QMetry Result

Location

Release

Contains test suites or test cycles

Folder

Top level

Release

Contains test cases directly

Test Suite

Under the corresponding release folder

Test Cycle

Contains child cycles or test suites

Folder

Under its release folder

Test Cycle

Contains test cases directly

Test Suite

Under the corresponding test cycle folder

Test Cycle

Has no child cycles or test suites

Test Suite

Under its parent

Test Suite

Always

Test Suite

Under its test cycle or release folder

5. Test Runs

qTest Test Runs are migrated as QMetry Test Runs, along with:

Migrated Data

Level

Execution statuses

Run

Defect links

Run

Attachments

Run

Comments

Run

Actual results

Both test step and test execution level

Capabilities of the Migration Tool

  • Migrates Tests and all their fields, rich text in Test Steps.

  • Migrates Test Data in Test Steps, Test Suites, Test Runs or Executions.

  • Migrates Jira Stories/Tasks, bugs through Jira Integration feature of QMetry.

  • Migrates custom fields and their values for all the assets.

  • Migrates folder structure. 

  • Migrates Releases and their data.

  • Migrates comments for all the assets.

  • Migrates linkages between assets.

  • Migrates all the attachments and URL links.

  • Support for mapping of qTest enumerated fields and their values with QMetry fields.

System Requirements

  • Java25 need to be installed. Reference: Archived OpenJDK GA Releases

  • MySQL services and MySQL Workbench 5.7 or above need to be installed. Reference: MySQL :: Download MySQL Installer

  • Operating Systems: Windows 10

  • CPU: 8 Cores, RAM: 16 GB

  • qTest cloud version 2025.8 (Utility is tested on)

  • Get your QMetry Migration Tool (migrate2qtm.war) and its license (qmetry-license-version-1.0) from Professional Services team.

  • QMetry and qTest should be running on your system with valid license.

  • Set UTC Time Zone in QMetry as all the dates from qTest will be migrated in to QMetry as per UTC time zone.

Prerequisites

  • Turn off API limits and Audit Logging.

    • For QMetry server:

      • These steps need to be followed in the QMetry database. Enter 'root' database credentials when prompted.

        sudo su -
docker exec -it qmetry_rds_1 bash
mysql -uroot -p -A
USE qmetry;

      • Run the following SELECT query check the status and the UPDATE query to disable audit logs and email notifications.

      • 0=disabled 1=Enabled

        SELECT CAST(isEmailEnabled AS UNSIGNED) as isEmailEnabled , CAST(isLogEnabled AS UNSIGNED) as isLogEnabled from client;
UPDATE `client` SET `isEmailEnabled` = b'0', `isLogEnabled` = b'0';

      • To enable them back (after migration is complete) run the following UPDATE query, and to check its updated value run the SELECT query.

        UPDATE `client` SET `isEmailEnabled` = b'1', `isLogEnabled` = b'1';
SELECT CAST(isEmailEnabled AS UNSIGNED) as isEmailEnabled , CAST(isLogEnabled AS UNSIGNED) as isLogEnabled from client;

      • Type \q to exit MySQL DB.

      • Type exit to exit the docker container.

    • For QMetry cloud:

      • Contact Professional Services team to turn off the API limits.

  • [Optional] Install Certificate in JDK on the machine running the migration utility.

  • Remove/rename duplicate list values for system/custom fields in qTest as QMetry does not support creation of duplicate values.

  • Create a Template Project in QMetry. The purpose of template project is to create a project structure that will be used to migrate the actual qTest project with data into QMetry. In this template project, create and link the qTest users. Refer to  Users in QMetry.

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" beside migrate2qtm.war file.

  • Run the following command by giving the path of the migrate2qtm.war file

    cd <PATH_TO_WAR_FILE>
java -jar migrate2qtm.war --spring.datasource.username=<dbusername> --spring.datasource.password=<dbpwd> --qTest.user.context.token = “<token>” --qtest.parameters.host =”<parameter host URL>”

  • Get QTest Parameter Host: Open any project on QTest instance and go to Parameters Section > Copy the parameter URL and add it in the command.

    Example 64. 

    qtest.parameters.host=https://parameter-13.qtestnet.com



  • Get the cookies/qTest.user.context.token: Open any project of qTest and open the developer tools of browser > Go to Network tab to check the API and refresh browser > Open any API on developers tool of the browser and navigate to Headers section of the API, like below > Check the cookies of the Headers section, copy the UserContextToken data and add it in command. Example: --qTest.user.context.token = “UserContextToken=ZTVhNTM1NzgtM2QxZC00M2IxLTgzOWEtOTAyMmEzNmNmZTRi”

Note

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 qTest and proceed with steps below:

  1. Destination Login

    Select QMetry as destination from the Destination selection screen. On selecting QMetry, the authentication page will open. We recommend logging in using admin credentials so that the projects available for migration are not restricted by a user's permissions.

    • Base URL: Your QMetry login URL. For example: https://testmanagement.qmetry.com

    • API Key: QMetry Open API Key from: QMetry> Integrations > Open API

  2. Source Login

    • qTest

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

      • Base URL: qTest URL in the format: https://<IP Address/URL>

      • Email : qTest user's login email

      • Password: qTest user's login password

        QPro_Migration_QMetryLogin.png

      • Select the check box for Jira integration authentication.

    • Jira authentication for Jira Integration

      If you use Jira for stories and bugs, then click on 'Select if you want to Integrate your qTest project to Jira project(s)' check box.

      We recommend logging in using admin credentials so that the projects available for migration are not restricted by a user's permissions.

      • Jira account type: Choose whether Cloud or Server

      • Jira URL: Your Jira URL

      • Jira Email ID: Email id used for Jira login

      • Jira API token: Get the API token from: Atlassian Account settings > Security > Create and manage API token > Create API token

        Jira_authentication_for_Jira_Integration.png

        Note

        If you do not select Jira integration, then you are confirming that Defect Linkage and Requirement Linkage will not migrate.

  3. Pre-requisites

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

    QTest_Prerequisites.png

  4. Project Selection

    1. qTest project and QMetry template project:

      • Select qTest Project you would like to migrate into QMetry. Also, select the QMetry Project Template to be used to create the project structure. The template project should be empty with 'Rich text enabled' and users linked to it.

      • Project key and Project Lead can be given by selecting the Create Project Key and Choose Project Lead checkbox.

    2. Jira Project Selection

      • Select the Jira projects that you want to integrate with the project which is currently being migrated.

        Jira_Project_Selection.png

  5. Entity Mapping

    • Jira Entity Mapping:

      Under this section, for each selected Jira project, map your Jira assets i.e Story/task/Bug or any other custom Issue-type to Requirement and Issue(defect) entities of QMetry. These assets will be migrated through Jira Integration feature of QMetry.

      Note

      If the QMetry Requirement is mapped to any Jira issue type then it is mandatory to map QMetry Issue module to at least one Jira issue type.

      EntityMapping.png

    • QMetry Entity Mapping

      Under this section, verify your qTest assets mapped to relevant QMetry Assets. Here, user can 'check/un-check' the entity which he wishes to migrate/not migrate as per the business requirement. The un-checked entities will not get migrated.

      QMetryEntityMapping.png

    • Execution capping:

      User can select this option incase he wants to migrate the test executions from a specific date and not all the legacy test execution data. This helps to clean up unwanted legacy data which improves migration time.

      Execution_capping.png

  6. Custom Fields

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

    Note

    This is an important step to ensure there is no data loss when the project is migrated to QMetry. 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 QMetry and will be auto mapped with the appropriate fields in the field mapping page.

    • Custom Field for qTest Requirements

      Custom_Field_for_qTest_s_Requirements.png

    • Custom Field for qTest Test cases

      Custom_Field_for_qTest_s_Test_cases.png

    • Custom Field for qTest Test suites

      Custom_Field_for_qTest_s_Test_suites.png

    • Custom Field for qTest Defects

      Custom_Field_for_qTest_s_Defects.png

  7. Field Mapping

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

    Note

    Any mandatory field of qTest should be mapped to mandatory field of QMetry. The field type of the mapped fields of qTest and QMetry should be same.

    • Field Mapping for qTest Requirement → QMetry Requirement

      Field_Mapping_for_qTest_Requirement.png

    • Field Mapping for qTest Test Case→ QMetry Test Case

      Field_Mapping_for_qTest_Test_Case_.png

    • Field Mapping for qTest Test Suite → QMetry Test Suite

      Field_Mapping_for_qTest_Test_Suite.png

    • Field Mapping for qTest Defect → QMetry Defect

      Field_Mapping_for_qTest_Defect.png

  8. Field Value Mapping

    You can map the values of your different enumerated fields of qTest to that of QMetry.

    Migration Tool provides an option of "Add value" if user wants to create a new field value in QMetry same as that of qTest. To create the new values: Click on the checkbox beside the field value > Click on "Add value" button below > Now map the qTest field values to the newly created QMetry 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 QMetry before beginning the migration process.

    • Field Value Mapping for Requirements

      QPro_Field_Value_Mapping_for_Requirements.png

    • Field Value Mapping for Test Cases

      Field_Value_Mapping_for_Test_Cases1.png

    • Field Value Mapping for Test Suites

      Field_Value_Mapping_for_Test_Suites.png

  9. Migration

    Click Migrate to start the migration process.

    QPro_Migration_MigrationButton.png

    Monitor the progress until the migration is complete.

    QPro_Migration_MigrationStatus.png

    Once the migration is completed, you can log in to QMetry 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 need to create a ticket on QMetry Professional Services support. Along with it 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.

  • Reverting API metering, Audit history logging and Email Notifications.

    Refer to the Pre-requisite for more details.

    • Run the following UPDATE query, and to check its updated value run the SELECT query.

      UPDATE `client` SET `isEmailEnabled` = b'1', `isLogEnabled` = b'1';
SELECT CAST(isEmailEnabled AS UNSIGNED) as isEmailEnabled , CAST(isLogEnabled AS UNSIGNED) as isLogEnabled from client;

Important Notes and Limitations

  • Dashboards, To Do, Reports of Projects, Overview, Activities, Graphs, History logs will not be migrated.

  • The users need to be created and linked to the template project manually before starting the migration. qTest users cannot be migrated to QMetry through migration utility.

  • Only latest result of a test run will get migrated as execution. The execution history can be viewed under Audit logs in QMetry.

  • QMetry does not provide customization at test execution level. Hence, custom fields of qTest at execution level will not migrate.

  • Attachments greater than 100 MB(for QTM cloud) or 300 MB(for QTM 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 QMetry, the entity assigned to him in qTest, gets assigned to that user in QMetry.

    • If the user is not found in QMetry, but the selected Project Lead user is present in QMetry, the assets of qTest are assigned to that user.

    • If the user is not found in QMetry and Project Lead is not selected, the assets are assigned to the user conducting the migration.

  • QMetry Testcase: Estimated time maximum value is 99999 mins; the value will be skipped for Estimated time and 99999 mins.

  • Temporarily deleted testcase will not get migrated until they are restored before starting the migration process.

  • Testcase sharing and cross project testcase execution linkage is not supported through migration utility.

  • If a project has both internal defects as well as Jira integrated defects, then only Jira defects will get integrated. The skipped internal defects and their corresponding linkages will get listed in the log file.

  • Only 500 rows will be migrated in a Dataset as limit of QMetry.

  • For Releases, only release name, description ,start date and end date will get migrated. Additional fields(system/custom) such as status, release and build note, attachments, etc. will not be migrated as it is not supported in QMetry.

  • Any entity(requirement, testcases, defects, test sets) or Release/cycle deleted temporarily will not be migrated. Temporarily deleted data must be restored in order to migrate.

  • Only the approved versions of the testcases will be migrated.

  • Sessions list of all the entity is not supported.

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 QMetry Professional Services Portal. We would be happy to assist you!

In this section:
© 2026
Publication date: