TestRail 10.3.1 is available for all Server customers. Customers who wish to upgrade to TestRail 10.3.1 can download the installation files from the TestRail Billing Portal.
This guide provides instructions for upgrading TestRail Server on Windows from any supported version (starting at 9.4.1) to any later version. You can use this document whether you are upgrading to 10.3.1 or to any earlier supported target version (starting at 9.4.1). Please follow these steps to upgrade your TestRail installation.
ℹ️ Important Note:
Starting with TestRail 9.5.1 Server, Cassandra is officially deprecated and enforcement is in place.
Admins must first run the Cassandra deprecation script in version 9.4.1 before upgrading to more recent versions.
-
If the script has not been executed, the upgrade to more recent versions will be blocked and a warning message will be displayed during the upgrade process.
👉 Please check our Cassandra Deprecation documentation.
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.
Install Chrome Headless Shell Dependency
- Install Dependencies - Please ensure that your system has the ability to unarchive ZIP files.
- Download Chrome Headless Shell Manually - Open the Chrome for Testing website in a browser and download the latest stable version
- Unzip the File - Right-click the .zip and select "Extract All"
- Move to Desired Location - Move the extracted folder anywhere (e.g., C:\Program Files\ChromeHeadless). Keep note of the location where you will move the binary, as you will need to add this path to the TestRail configuration.
Remove Old Files and Extract New Installation Files
To upgrade your TestRail installation, in TestRail 10.0.1 you must delete all old installation files in the instance's folder, except for the user-created files/folders (e.g. config.php, logs, and audit folders), before extracting the TestRail 10.0.1 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.
Update Jira token configuration (Required for versions below 10.1.4)
If you are upgrading from a version earlier than 10.1.4, you must update the Jira token configuration file as part of this process.
- Download the update files here.
- Update the files
- Locate your TestRail installation path
Replace
app/config/consts.phpwith the updated version provided
Now, you will need to add a new entry in config.php:
define('TR_CHROME_PATH', 'C:\\testrail\\chrome-headless-shell-win64\\chrome-headless-shell.exe');
Once the above has been done, you can Log into the instance via a web browser (usually ‘http://localhost/testrail/’ or something similar) to confirm a successful upgrade.
Clear browser cache
Once the upgrade has been confirmed, all end-users will be required to clear their browser cache so the jQuery upgrade will take effect. Please follow the following steps to accomplish this on each of our supported browsers:
- Chrome - https://support.google.com/accounts/answer/32050?hl=en&co=GENIE.Platform%3DDesktop
- Firefox - https://support.mozilla.org/en-US/kb/how-clear-firefox-cache
- Microsoft Edge - https://www.microsoft.com/en-us/edge/learning-center/how-to-manage-and-clear-your-cache-and-cookies?form=MA13I2
- Safari - https://support.apple.com/lv-lv/guide/safari/sfri11471/mac
Troubleshooting
If you override current TestRail installation with new files, then you have to delete a folder from the previous version:
- /app/libraries/PhpSpreadsheet folder