Add multi-PHP, environment labels, and commit tracking.

.env.default

@@ -11,6 +11,10 @@
 # $ source .env
 ###
 
+# Optional label to distinguish this environment in test reports, for example
+# "shared", "vps", or "cloud". Use a single alphanumeric keyword.
+export WPT_LABEL=""
+
 # Path to the directory where files can be prepared before being delivered to the environment.
 export WPT_PREPARE_DIR="/tmp/wp-test-runner"
 
@@ -35,7 +39,18 @@ export WPT_DB_HOST=""
 # (Optionally) set a custom table prefix to permit concurrency against the same database.
 export WPT_TABLE_PREFIX="${WPT_TABLE_PREFIX-wptests_}"
 
-# (Optionally) define the PHP executable to be called
+# PHP executable to be called. Default: php
+#
+# A single binary:
+#   export WPT_PHP_EXECUTABLE="php"
+#   export WPT_PHP_EXECUTABLE="/usr/bin/php8.1"
+#
+# Multiple versions (version=path, separated by semicolons). Each version
+# gets its own prepare/test directories and database table prefix:
+#   export WPT_PHP_EXECUTABLE="8.1=/bin/php8.1;8.2=/bin/php8.2;8.3=/bin/php8.3"
+#
+# Use as many versions as you'd like, but keep in mind that it will take more time.
+# Ideally all versions offered to users are tested.
 export WPT_PHP_EXECUTABLE="${WPT_PHP_EXECUTABLE-php}"
 
 # (Optionally) define the PHPUnit command execution call.
@@ -83,3 +98,12 @@ export WPT_FLAVOR=0
 # 2 = ms-files
 # 3 = external-http
 export WPT_EXTRATESTS=0
+
+# Whether to queue recent wordpress-develop commits instead of only the latest.
+#
+# 0 = Off. Test only the most recent commit when the runner starts.
+# 1 = On. Query the last 30 commits and queue any that have not been tested yet.
+#
+# Regardless of this value, commits.json tracks SHAs that were already tested
+# and reported so the suite is not re-run for the same commit.
+export WPT_COMMITS=0

.gitignore

@@ -4,6 +4,7 @@ vendor/
 .cache/
 package-lock.json
 commit.json
+commits.json
 ignore.json
 
 # Exclude the default test directory.

README.md

@@ -626,6 +626,28 @@ journalctl -u testrunner.timer
 journalctl -n 120 -u testrunner.service
 ```
 
+## Multiple PHP versions, environments, and commits
+
+These options are configured in `.env`. Broader documentation updates live in a separate pull request; this section only covers the runner behavior added for multi-PHP, environment labels, and commit tracking.
+
+**Environment label.** Set `WPT_LABEL` to a short alphanumeric keyword such as `shared`, `vps`, or `cloud`. The label is included in the reported environment details so results from different setups on the same host can be distinguished.
+
+**Multiple PHP versions.** `WPT_PHP_EXECUTABLE` still defaults to `php`. A single binary path continues to work as before. To test more than one version, use `version=path` entries separated by semicolons:
+
+```bash
+export WPT_PHP_EXECUTABLE="8.1=/bin/php8.1;8.2=/bin/php8.2;8.3=/bin/php8.3"
+```
+
+Each version uses its own prepare/test directory (the version is appended in plain text, for example `/tmp/wp-test-runner-8-1`) and a unique database table prefix so runs do not collide.
+
+**Commit tracking.** The runner writes `commits.json` (gitignored; copied from `commits.json.example` when missing):
+
+- `executed_commits`: SHAs that were successfully tested and reported
+- `pending_commits`: SHAs waiting to be tested (oldest first)
+- `testing_commit`: the SHA currently being tested (at most one)
+
+`WPT_COMMITS=0` tests only the latest commit when the runner starts. `WPT_COMMITS=1` queries the last 30 wordpress-develop commits (the GitHub API default page size) and queues any that have not been tested yet. In both modes, a commit already present in `commits.json` is skipped.
+
 ## Contributing
 
 If you have questions about the process or run into test failures along the way, please [open an issue in the project repository](https://github.com/WordPress/phpunit-test-runner/issues) and we’ll help diagnose/get the documentation updated. Alternatively, you can also pop into the `#hosting` channel on [WordPress.org Slack](https://make.wordpress.org/chat/) for help.

cleanup.php

@@ -1,22 +1,15 @@
 <?php
 /**
- * WordPress PHPUnit Test Runner: Cleanup script
- *
- * This script is responsible for cleaning up the test environment after the
- * Test Runner completes.
- *
- * All files and directories created by the test runner or the PHPUnit test
- * suite are removed.
+ * This script is responsible for cleaning up the test environment after a run of the WordPress PHPUnit Test Runner.
+ * It ensures that temporary directories and files created during the test process are properly deleted.
  *
  * @link https://github.com/wordpress/phpunit-test-runner/ Original source repository
- *
  * @package WordPress
  */
 require __DIR__ . '/functions.php';
 
-/*
+/**
  * Check for the presence of required environment variables.
- *
  * This function should be defined in functions.php and should throw an
  * exception or exit if any required variables are missing.
  */
@@ -27,36 +20,28 @@
  */
 $runner_vars = setup_runner_env_vars();
 
-/*
- * Clean up the test preparation directory.
- *
- * This ensures a clean slate the next time the test runner is executed.
- *
- * `WPT_PREPARE_DIR` will exist so long as prepare.php ran correctly.
- *
- * The following actions are performed:
- * - Forcefully deletes only the .git directory and the node_modules cache.
- * - Forcefully remove the `node_modules/.cache` directory.
- * - Remove the entire preparation directory.
- */
-perform_operations(
-	array(
-		'rm -rf ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] . '/.git' ),
-		'rm -rf ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] . '/node_modules/.cache' ),
-		'rm -r ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] ),
-	)
-);
+skip_if_no_prepared_environment( $runner_vars );
 
-/*
- * Clean up the test directory on a remote server.
- *
- * This ensures a clean slate on the remote server the next time the test
- * runner is executed.
- */
-if ( ! empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
-	perform_operations(
-		array(
-			'ssh ' . $runner_vars['WPT_SSH_OPTIONS'] . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] ) . ' ' . escapeshellarg( $runner_vars['WPT_RM_TEST_DIR_CMD'] ),
-		)
-	);
+foreach ( $runner_vars['WPT_PHP_EXECUTABLES'] as $php ) {
+	$paths = get_php_run_paths( $runner_vars, $php );
+
+	log_message( 'Cleaning environment for PHP ' . $php['version'] );
+
+	if ( is_dir( $paths['prepare_dir'] ) ) {
+		perform_operations(
+			array(
+				'rm -rf ' . escapeshellarg( $paths['prepare_dir'] . '/.git' ),
+				'rm -rf ' . escapeshellarg( $paths['prepare_dir'] . '/node_modules/.cache' ),
+				'rm -r ' . escapeshellarg( $paths['prepare_dir'] ),
+			)
+		);
+	}
+
+	if ( ! empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
+		perform_operations(
+			array(
+				'ssh ' . $runner_vars['WPT_SSH_OPTIONS'] . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] ) . ' ' . escapeshellarg( $paths['rm_cmd'] ),
+			)
+		);
+	}
 }

commits.json.example

@@ -0,0 +1,5 @@
+{
+	"executed_commits": [],
+	"pending_commits": [],
+	"testing_commit": ""
+}