Ready-made scripts for hosts that run the test runner on their own servers. Use them in place of writing your own setup and cron scripts.
| Script | What it does |
|---|---|
setup.sh |
Checks the required software, creates .env with prompts, and tests the database connection. |
testrunner.sh |
Runs the full test cycle in one step: update, prepare, test, report and clean up. |
The scripts do not change the runner itself. They use the same .env file and the same PHP files (prepare.php, test.php, report.php, cleanup.php) as a manual setup.
You need:
- A Linux server with the usual configuration you give to your customers.
- A non-root user to run the tests.
- A database and a database user that are only for the tests. The test suite deletes and creates tables in this database.
- The software in the Requirements section of the main README: PHP, Git, rsync, wget, unzip, Node.js and npm. Composer is optional.
The scripts do not install software, create the database, or set up cron.
-
Clone the runner as the test user:
git clone https://github.com/WordPress/phpunit-test-runner.git cd phpunit-test-runner -
Create
.env:./host-tools/setup.sh
The script asks for the database credentials, the PHP executable, the checkout directory and the report API key. Press Enter to keep the value in brackets. If it cannot connect to the database, it stops and does not change
.env. -
Run the tests once and read the output:
./host-tools/testrunner.sh
A run can take a long time. Each run clones WordPress and installs the npm and Composer dependencies again.
-
Run the tests on a schedule. For example, a cron entry for every 4 hours. Replace
/path/to/phpunit-test-runnerwith the directory of your clone:PATH=/usr/local/bin:/usr/bin:/bin 0 */4 * * * /path/to/phpunit-test-runner/host-tools/testrunner.sh >> /path/to/testrunner.log 2>&1Cron starts with a short
PATH, andprepare.phpcallsnpmandcomposer. Set aPATHthat finds them.The script finds the runner from its own location, so cron does not need to change to that directory first.
To report results to the Host Test Results page, you need a bot user with the "Test Reporter" role. See How to report. After you get the application password, run ./host-tools/setup.sh again and enter it as botuser:application password.
./host-tools/setup.sh [--non-interactive] [--skip-checks] [--skip-db-check]| Option | Effect |
|---|---|
--non-interactive |
Do not ask. Use values from the environment and the current .env. For provisioning tools. |
--skip-checks |
Do not check the required software. |
--skip-db-check |
Do not test the database connection. |
- Values come from the environment first, then from the current
.env, then from the defaults. - For a run on this server, the script sets
WPT_TEST_DIRto the same directory asWPT_PREPARE_DIR, which the runner requires. WithWPT_SSH_CONNECTset, it keepsWPT_TEST_DIR, the directory on the remote server. - Settings that the script does not ask about, like the SSH settings, stay as they are in the current
.env. - It saves the old
.envas.env.bak-<date>. The new.envand the backup are readable only by their owner.
Example for a provisioning tool:
WPT_DB_NAME=wptests WPT_DB_USER=wptests WPT_DB_PASSWORD=secret \
WPT_REPORT_API_KEY='botuser:application password' \
./host-tools/setup.sh --non-interactive./host-tools/testrunner.sh- Stops if
.envdoes not exist. - Stops if another run of the same checkout is still active. This uses
flock, which most Linux systems have. Withoutflock, the script does not check for other runs. - Updates the runner with
git pull --ff-only origin master. If the update fails, the script shows a warning and continues. - Runs
prepare.php,test.php,report.phpandcleanup.phpwith the PHP executable fromWPT_PHP_EXECUTABLE. WithWPT_SSH_CONNECTset,WPT_PHP_EXECUTABLEis the PHP on the remote server, so these run with the localphp.
Behavior when a step fails:
- When a test fails, the script still runs the report, so the failure shows on the results page.
- When
prepare.phpfails, the script skips the tests and the report. - The script always runs
cleanup.php, also when a step fails or the run is stopped. - The exit status is
0when every step succeeds and1when any step fails.
| Environment variable | Effect |
|---|---|
WPT_RUNNER_DIR |
The runner directory. Default: the directory above host-tools/. |
WPT_SKIP_UPDATE=1 |
Skip git pull, for example when you test local changes. |
- Keep the scripts in Bash, and do not change the runner's PHP files from them.
- Test changes on a Linux server, with a successful run and with a failed step.
- Update this README when you add a script or an option.