Upgrading TestRail from 7.5.3 to 8.0.1 in Windows

Below, you will find information on how to upgrade an existing TestRail installation to a new version (7.5.3 to 8.0.1). Please follow these steps to upgrade your TestRail installation.

As of TestRail 8.0.1, PHP 7.4 is no longer supported. You can learn how to upgrade PHP here.

Backup

It is strongly recommended to make a backup of your TestRail installation files and TestRail database before upgrading to a newer version. In case there’s a problem with the upgrade, a backup is the only way to roll back the changes and revert to your previous (working) installation. We recommend making backups of your TestRail installation and database regularly, especially before upgrading to a newer version.

Requirements

Before proceeding with an upgrade to TestRail, please review the requirements documentation and operating specific instructions (Windows/Linux). Software dependencies such as PHP and SQL can change over time, so it is important to review these requirements prior to updating your TestRail software.

Upgrading the dependencies

PHP 8.1

TestRail 8.0 requires PHP 8.1.  The first step in this upgrade is to install PHP 8.1.

Download the official PHP files here.

As of 2023, VS16 x64 Non Thread Safe  is the recommended version to download, as this will be used in the installation documentation.

Once the download is complete, extract the zipped PHP files into C:\php\ on the host system.

Edit your Environment Variables,  and add a new Path System variable C:\php. 

Now update Handler Mappings in IIS with the new php path. Go to the IIS Manager, click on the server host, then click Handler Mappings, and Add Module Mapping.

On the new window, fill in all the fields with the exact information shown on the following image, and then click OK.

Go back to the server host in the IIS Manager, and this time click Default Document. Click Add on the Actions Panel.

Fill in the Name field with Index.php and click OK. Next, click Add again and this time fill in the Name field with Default.php and click OK.

PHP extensions

To use TestRail on Windows with a SQL Server database, the following PHP extensions are required:

• cassandra extension to access the NoSQL database
• gd PHP extension for generating charts
• sqlsrv_81_nts_x64 PHP extension to access SQL Server databases
• pdo_mysql PHP extension to access the database
• fileinfo PHP extension for determining file type and encoding
• imagick PHP extension for working with images
• mbstring PHP extension for working with Unicode strings
• curl PHP extension to check for updates etc.
• openssl PHP extension to handle SSL connections
• ioncube PHP loader to decode the TestRail PHP files

To download the PHP Microsoft drivers for SQL Server here, and click Download Microsoft Drivers for PHP for SQL Server (Windows).

Once you extracted the files, copy the following files to your C:\php\ext\ directory: 

• • php_pdo_sqlsrv_81_nts_x64.dll
  • sqlsrv_81_nts_x64

To install these extensions, add the following to your php.ini files:

• • extension=pdo_sqlsrv_81_nts_x64
  • extension=sqlsrv_81_nts_x64

For the imagick extension installation, follow the instructions in the official documentation. 

The last required PHP extension is the free ionCube PHP loader. You can download the ionCube loader for Windows here.

This installation procedure requires ‘ioncube_loader_win_8.1.dll’, which is found downloading the Windows VC16 (Non-TS) (64 bits) zip file (ioncube_loaders_win_nonts_vc16_x86-64.zip). Extract all the files on your server, and copy the loader extension to your PHP’s ext directory (usually C:\php\ext\). Next, activate the extension by adding the following line to your PHP.ini file (You can find this file in your installation directory, usually C:\php\):

zend_extension = "C:\php\ext\ioncube_loader_win_8.1.dll"

To verify that the ionCube loader extension has been successfully installed, run php -v in the Windows Command Prompt (you need to change to PHP’s installation directory in order to execute this command).

The ionCube loader extension is successfully installed if php -v outputs something like this (note the ionCube PHP Loader line):

PHP 8.1.14 (cli) (built: Jan 4 2023 12:24:57) (NTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.1.14, Copyright (c) Zend Technologies
with the ionCube PHP Loader v12.0.5, Copyright (c) 2002-2022, by ionCube Ltd.

Most extensions should be added automatically, but you will need to run through the additional Cassandra, IonCube, and imagick steps. If you installed PHP manually, you might have to activate the required extensions in the PHP.ini file like this:

zend_extension = "C:\php\ext\ioncube_loader_win_8.1.dll"
extension=cassandra
extension=gd
extension=fileinfo
extension=imagick
extension=mbstring
extension=curl
extension=openssl
extension=pdo_sqlsrv_81_nts_x64
extension=sqlsrv_81_nts_x64

To reload PHP, restart the IIS web server. The easiest way to do this is to restart the World Wide Web Publishing Windows service. You can do this by opening the Services application from the Administrative Tools and restarting the service. Please note that this restarts all IIS application pools and websites. If you are hosting other websites and applications on this server, you might want to restart the relevant application pool only.

Replace installation files

To upgrade your TestRail installation, upload and extract the TestRail installation files to your web server and copy the files of the new TestRail version over your existing installation files. You can just replace all files, as files that are unique to your installation (e.g. the config.php file) aren’t part of the installation archive.

Once the files have been replaced, the instance has been upgraded.  Log into the instance via web browser (usually ‘http://localhost/testrail/’ or something similar) to confirm a successful upgrade.

MAX_CHART_ROWS

If users upgrade to 8.0 without adding MAX_CHART_ROWS to the config.php file, an error appears like the one shown below:

To fix this, add the constant:

/*
|--------------------------------------------------------------------
| OPTIMIZATIONS
|--------------------------------------------------------------------
|
| You can choose whether to optimize the delivery of style sheet and
| javascript files and the handling of language files. The following
| optimization settings are available:
|
| DEPLOY_OPTIMIZE_LANG:   If enabled, TestRail uses a single combined
|                         language file named 'all_lang' instead of
|                         multiple language files.
|
| DEPLOY_OPTIMIZE_CSS:    If enabled, a single combined style sheet
|                         is served to the clients.
|
| DEPLOY_OPTIMIZE_JS:     If enabled, a single combined javascript
|                         file is served to the clients.
*/


define('DEPLOY_OPTIMIZE_LANG', true);
define('DEPLOY_OPTIMIZE_CSS', true);
define('DEPLOY_OPTIMIZE_JS', true);


define('MAX_CHART_ROWS', 150000);