The TestRail background task is responsible, among other things, for sending out email notifications for test changes if this feature is enabled. The background task is a simple PHP script that needs to be triggered at regular intervals to do its work.
The easiest way to do this is to schedule it as a background job with the tools your operating system provides. See below on how to install the background task on Windows and Unix/Linux operating systems.
Background task on Windows
We use the Windows Task Scheduler to trigger the background task periodically. Before scheduling the task, you can verify that it can be successfully started by running it manually from the command line (x86 and x64):
Update the “x.x” with the actual version number.
> "C:\Program Files\PHP\x.x\php.exe" "C:\inetpub\wwwroot\testrail\task.php" > REM Or, for x64 systems: > "C:\Program Files (x86)\PHP\x.x\php.exe" "C:\inetpub\wwwroot\testrail\task.php"
Check the actual path to PHP on your system as this can differ depending on the PHP version you’re using.
The TestRail background task automatically detects if it’s already running, so it’s best to trigger the task in very short intervals (such as every minute) for best results. To do this, open the Windows Task Scheduler and select Create Basic Task (Windows 2008).
Now, specify a task name and select to trigger the task even if no user is logged on:
On the Triggers tab, add a new trigger to specify when the task should be executed:
And last but not least, add the action to execute the TestRail task script on the Actions tab.
Because the script is a PHP script, we need to specify the path of the php.exe and the task.php script as an argument (including quotes):
Alternatively to using the Task Scheduler GUI, you can also create the task using the command line. For example, on Windows Server 2008:
schtasks /create /np /sc minute /mo 1 /tn "TestRail Background Task" /tr "\"C:\Program Files (x86)\PHP\v7.4\php.exe\" C:\inetpub\wwwroot\testrail\task.php"
Background task on Unix/Linux
cron to trigger the background task on Unix/Linux systems periodically. Before scheduling the task, you can verify that it can be successfully started by running it manually from the command line:
$ php /var/www/html/testrail/task.php
The TestRail background task automatically detects if it’s already running, so it’s best to trigger the task in very short intervals (such as every minute) for best results. To do this, make sure cron is installed on your system and create a file
/etc/cron.d/testrail with the following content:
* * * * * www-data /usr/bin/php /var/www/html/testrail/task.php
The cron job needs the PHP command-line interface, which might already be installed on your system. You can test this by executing the php -v command. If it’s not already installed, install the php7.2-cli package or equivalent with your platform’s package manager.
Also, make sure to add the above-mentioned PHP extensions to the php-cli’s PHP.ini if it doesn’t use the web server’s PHP.ini file. E.g., on Ubuntu systems, also add the ioncube extension to /etc/php/7.2/cli/php.ini.