TestRail 8.0 is available for Server customers who wish to upgrade urgently to an "early access" version. We recommend that all other customers wait until the "default" version of TestRail 8.0 is available. TestRail 8.0 "default" will be available after the release is deployed to cloud customers.
Below, you will find information on how to upgrade an existing TestRail installation to a new version (7.5.3 to 8.0). Please follow these steps to upgrade your TestRail installation.
As of TestRail 8.0, PHP 7.4 is no longer supported. You can learn how to upgrade PHP here.
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.
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
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.
To run your PHP info diagnostics and check the PHP Version, follow the instructions here.
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:
To install these extensions, add the following to your php.ini files:
For the imagick extension installation, follow the instructions in the official documentation.
Refer to the Cassandra installation instructions for more details about Cassandra prerequisites and full installation/configuration.
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.
In order for IIS to be able to load the extension, you might need to change the permission of the ionCube extension file. To do this, right-click the file in Explorer, click Properties, select the Security tab, and add the Users group.
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.
Some web server configurations can prevent files from being overridden while the web server is active. You need to stop the web server before replacing TestRail’s installation files. This happens mainly with Windows/IIS systems, so if you have upgrade issues, try stopping the web server and overriding the files again.
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.
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: