Activating the background task

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):

> "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"

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):

"C:\inetpub\wwwroot\testrail\task.php"

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

We use 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.