Zephyr Testrail Project Migration

Table of Contents

Zephyr Testrail Migration:

Zephyr Testrail Migration is a unique API driven solution that lets you migrate your data from Testrail directly into Zephyr. Zephyr offers dedicated migration service offering that can speed up the transition phase from tools such as Testrail. Zephyr team can assist in the migration process end to end, which includes - planning, prepping the environment, data migration and verification.

Planning and Prerequisites:

Planning is an important phase of migration. This phase involves the required prerequisite softwares to be installed before proceeding with the Testrail Project Migration:

  • PHP Version 7.2.9
  • Composer Version 1.4.2
  • MySQL Version 5.7.22

PHP Setup:

  1. Navigate to the php.ini file
  2. Uncomment the following lines:
    1. extension = curl
    2. extension = fileinfo
    3. extension = mbstring
    4. extension = mysqli
    5. extension = openssl
    6. extension = pdo_mysql

MySQL Setup:

  1. Create a database and name the database: "testrail_migration"

Project Setup Instructions:

Below steps provides an overview the project setup instructions.

  1. Go to the project base folder.

  2. Copy the ".env.xperi" file contents into the ".env file".
  3. Change following properties in the ".env file" for the testrail_migration database (the MySQL database created):
    2. DB_HOST
    3. DB_PORT
  4. Change following properties in the ".env file" for the testrail database:
  5. Change the TESTRAIL_ATTACHMENTS_BASE_FILE_PATH property in the ".env file" to point to the path where the testrail attachments are stored.
  6. Change Testrail authentication and Zephyr authentication properties in the ".env file" as required.
    1. See Project Environment Variables below for more explanation.

Project Environment Variables:

These variables are available in the ".env file".

TestRail Migration Mapping Database Connection Variables: This is the database which stores entity mapping for Testrail and Zephyr. It tells which entity in Testrail server is mapped against which entity in Zephyr server.

  • DB_CONNECTION: Type of database
  • DB_HOST: Host for database server
  • DB_PORT: Port for database server
  • DB_DATABASE: Database name for testrail migration mapping db, default is testrail_migration
  • DB_USERNAME: Username for database server
  • DB_PASSWORD: Password for database server 

TestRail Database Connection Variables: This is the main database for the Testrail server.

  • DB_CONNECTION_TESTRAIL: Type of database
  • DB_HOST_TESTRAIL: Host for database server
  • DB_PORT_TESTRAIL: Port for database server
  • DB_DATABASE_TESTRAIL: Database name for testrail db, default is testrail
  • DB_USERNAME_TESTRAIL: Username for database server
  • DB_PASSWORD_TESTRAIL: Password for database server

TestRail Server Authentication Credentials: These variables contain necessary credentials to access testrail server. Make sure this user has the adequate permission to access data.

  • TESTRAIL_SERVER: API Url for the Testrail server.
  • TESTRAIL_USERNAME: Username for the Testrail server.
  • TESTRAIL_PASSWORD: Password for the Testrail server.

Zephyr Server Authentication Credentials: These variables contain necessary credentials to access the Zephyr server. Make sure this user has the adequate permission to create and access data.

  • ZEPHYR_SERVER: API Url for the Zephyr server.
  • ZEPHYR_USERNAME: Username for the Zephyr server.
  • ZEPHYR_PASSWORD: Password for the Zephyr server. 

TestRail Attachment File Path: This is the file path where attachments for testrail are stored. Make sure that the user has the adequate permission to read files.

  • TESTRAIL_ATTACHMENTS_BASE_FILE_PATH: File path for testrail attachments


Testrail Setup Instructions:

Below steps provides an overview the Testrail setup instructions to enable the API.

  1. Open the Testrail instance/environment server.

  2. Navigate to the following pages:
    1. Administration tab → Site Settings → API
  3. Check the checkbox for the "Enable API" field.
  4. Save the settings and the changes made.

This process allows access to the Testrail data though the usage of the API.

How to Migrate Instructions:

Below steps provides an overview on the how-to migration process.

  1. Run the following command to create tables in the testrail_migration database. This command will delete the old data and create new blank tables. Only do this when mapping in the database is not required.
    1. php artisan migrate:refresh
  2. Run the following command to start the migration process and provide the Testrail project id for the projectId option to migrate that project (xx = the Testrail project ID).
    1. php artisan zephyr-migrate:start --projectId=xx

Supported Migration Entities:

Zephyr is able to support the migration of the following Testrail entities (listed in the order of migration):

  1. Testrail Project → Zephyr Project
  2. Testrail Suites → Zephyr Phases
    1. Testrail Sections → Zephyr Phases
  3. Testrail Case Fields → Zephyr Testcase Custom Fields
  4. Testrail Test Execution Statues → Zephyr Execution Statuses
  5. Testrail Cases → Zephyr Testcases
  6. Testrail Case Attachments → Zephyr Testcase Attachments

If an error is being thrown for php extensions then you must install the proper php modules following the error input.

The MySQL server can be the same as the one on which Testrail and/or Zephyr are installed

Versions provided for the softwares are for when development was done using the softwares. These versions are not necessary but are recommended for the process to work without error.

Additional Questions:

For any questions, please contact Zephyr Support.