Merge branch 'master' into documentation-changes

Author: desrosj

.env.default

@@ -57,9 +57,16 @@ export WPT_SSH_OPTIONS=""
 # SSH private key, base64 encoded.
 export WPT_SSH_PRIVATE_KEY_BASE64=""
 
-# Output logging
-# Use 'verbose' to increase verbosity
-export WPT_DEBUG=""
+# Whether to enable debug Mode.
+#
+# Enabling debug mode will output verbose logging and details about each part
+# of the test runner.
+#
+# 0 = Debug mode off
+# 1 = Debug mode on
+#
+# Any other truthy value will also enable debug mode.
+export WPT_DEBUG=
 
 # Certificate validation
 # Use 1 to validate, and 0 to not validate
@@ -68,7 +75,7 @@ export WPT_CERTIFICATE_VALIDATION=1
 # WordPress flavor
 # 0 = WordPress (simple version)
 # 1 = WordPress Multisite
-export WPT_FLAVOR=1
+export WPT_FLAVOR=0
 
 # Extra tests (groups)
 # 0 = none

.github/workflows/props-bot.yml

@@ -76,7 +76,7 @@ jobs:
           format: 'git'
 
       - name: Remove the props-bot label
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         if: ${{ github.event.action == 'labeled' && 'props-bot' == github.event.label.name }}
         with:
           retries: 2

.github/workflows/tests.yml

@@ -67,13 +67,13 @@ jobs:
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Set up PHP
-        uses: shivammathur/setup-php@20529878ed81ef8e78ddf08b480401e6101a850f # v2.35.3
+        uses: shivammathur/setup-php@ec406be512d7077f68eed36e63f4d91bc006edc4 # v2.35.4
         with:
           php-version: '7.4'
           coverage: none
 
       - name: Install NodeJS
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           node-version: 20
 

cleanup.php

@@ -22,17 +22,10 @@
  */
 check_required_env();
 
-/*
- * Retrieve environment variables falling back to defaults.
- *
- * These variables are used to configure SSH connections, file paths, and
- * executable commands needed for setting up the test environment.
+/**
+ * Ensure that all environment variables are present with default values.
  */
-$WPT_PREPARE_DIR     = trim( getenv( 'WPT_PREPARE_DIR' ) );
-$WPT_SSH_CONNECT     = trim( getenv( 'WPT_SSH_CONNECT' ) );
-$WPT_SSH_OPTIONS     = trim( getenv( 'WPT_SSH_OPTIONS' ) ) ? : '-o StrictHostKeyChecking=no';
-$WPT_TEST_DIR        = trim( getenv( 'WPT_TEST_DIR' ) );
-$WPT_RM_TEST_DIR_CMD = trim( getenv( 'WPT_RM_TEST_DIR_CMD' ) ) ? : 'rm -r ' . $WPT_TEST_DIR;
+$runner_vars = setup_runner_env_vars();
 
 /*
  * Clean up the test preparation directory.
@@ -47,9 +40,9 @@
  * - Remove the entire preparation directory.
  */
 perform_operations( array(
-	'rm -rf ' . escapeshellarg( $WPT_PREPARE_DIR . '/.git' ),
-	'rm -rf ' . escapeshellarg( $WPT_PREPARE_DIR . '/node_modules/.cache' ),
-	'rm -r ' . escapeshellarg( $WPT_PREPARE_DIR ),
+	'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'] ),
 ) );
 
 /*
@@ -58,8 +51,8 @@
  * This ensures a clean slate on the remote server the next time the test
  * runner is executed.
  */
-if ( ! empty( $WPT_SSH_CONNECT ) ) {
+if ( ! empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
 	perform_operations( array(
-		'ssh ' . $WPT_SSH_OPTIONS . ' ' . escapeshellarg( $WPT_SSH_CONNECT ) . ' ' . escapeshellarg( $WPT_RM_TEST_DIR_CMD ),
+		'ssh ' . $runner_vars['WPT_SSH_OPTIONS'] . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] ) . ' ' . escapeshellarg( $runner_vars['WPT_RM_TEST_DIR_CMD'] ),
 	) );
 }

functions.php

@@ -44,6 +44,68 @@ function check_required_env( $check_db = true ) {
 
 	log_message( 'Environment variables pass checks.' );
 }
+
+/**
+ * Parses environment variables used to configure the test runner.
+ *
+ * @return array[] {
+ *      Test runner configuration options.
+ *
+ *      @type array ...$0 {
+ *          An associative array of test runner configuration options.
+ *
+ *          @type string $WPT_TEST_DIR               Path to the directory where wordpress-develop is placed for testing
+ *                                                   after being prepared. Default '/tmp/wp-test-runner'.
+ *          @type string $WPT_PREPARE_DIR            Path to the temporary directory where wordpress-develop is cloned
+ *                                                   and configured. Default '/tmp/wp-test-runner'.
+ *          @type string $WPT_SSH_CONNECT            List of inner blocks. An array of arrays that
+ *                                                   have the same structure as this one.
+ *          @type string $WPT_SSH_OPTIONS            HTML from inside block comment delimiters.
+ *          @type string $WPT_PHP_EXECUTABLE         List of string fragments and null markers where
+ *                                                   inner blocks were found.
+ *          @type string $WPT_RM_TEST_DIR_CMD        Command for removing the test directory.
+ *          @type string $WPT_REPORT_API_KEY         API key for submitting test results.
+ *          @type bool   $WPT_CERTIFICATE_VALIDATION Whether to validate TLS certificates. Default true.
+ *          @type bool   $WPT_DEBUG_MODE             Whether debug mode is enabled.
+ *      }
+ *  }
+ */
+function setup_runner_env_vars() {
+	// Set the test directory first as it's needed for processing other variables.
+	$runner_configuration = array(
+		'WPT_TEST_DIR' => trim( getenv( 'WPT_TEST_DIR' ) ) ?: '/tmp/wp-test-runner',
+	);
+
+	/*
+	 * When no value is provided for WPT_CERTIFICATE_VALIDATION, assume that the default of true (validate certificates)
+	 * is desired.
+	 */
+	if ( false === getenv( 'WPT_CERTIFICATE_VALIDATION' ) ) {
+		$runner_configuration['WPT_CERTIFICATE_VALIDATION'] = true;
+	} else {
+		$runner_configuration['WPT_CERTIFICATE_VALIDATION'] = (bool) getenv( 'WPT_CERTIFICATE_VALIDATION' );
+	}
+
+	return array_merge(
+		$runner_configuration,
+		array(
+			// Directory configuration
+			'WPT_PREPARE_DIR'            => trim( getenv( 'WPT_PREPARE_DIR' ) ) ?: '/tmp/wp-test-runner',
+			// SSH connection configuration
+			'WPT_SSH_CONNECT'            => trim( getenv( 'WPT_SSH_CONNECT' ) ),
+			'WPT_SSH_OPTIONS'            => trim( getenv( 'WPT_SSH_OPTIONS' ) ) ?: '-o StrictHostKeyChecking=no',
+			// Test execution configuration
+			'WPT_PHP_EXECUTABLE'         => trim( getenv( 'WPT_PHP_EXECUTABLE' ) ) ?: 'php',
+			// Cleanup configuration
+			'WPT_RM_TEST_DIR_CMD'        => trim( getenv( 'WPT_RM_TEST_DIR_CMD' ) ) ?: 'rm -r ' . $runner_configuration['WPT_TEST_DIR'],
+			// Reporting configuration
+			'WPT_REPORT_API_KEY'         => trim( getenv( 'WPT_REPORT_API_KEY' ) ),
+			// Miscellaneous
+			'WPT_DEBUG'                  => (bool) getenv( 'WPT_DEBUG' ),
+		)
+	);
+}
+
 /**
  * Executes a set of shell commands.
  *

prepare.php

@@ -19,36 +19,10 @@
  */
 check_required_env();
 
-/*
- * Retrieve environment variables falling back to defaults.
- *
- * These variables are used to configure SSH connections, file paths, and
- * executable commands needed for setting up the test environment.
+/**
+ * Ensure that optional environment variables are present with default values.
  */
-$WPT_PREPARE_DIR    = trim( getenv( 'WPT_PREPARE_DIR' ) );
-$WPT_SSH_CONNECT    = trim( getenv( 'WPT_SSH_CONNECT' ) );
-$WPT_SSH_OPTIONS    = trim( getenv( 'WPT_SSH_OPTIONS' ) ) ? : '-o StrictHostKeyChecking=no';
-$WPT_TEST_DIR       = trim( getenv( 'WPT_TEST_DIR' ) );
-$WPT_PHP_EXECUTABLE = trim( getenv( 'WPT_PHP_EXECUTABLE' ) ) ? : 'php';
-$WPT_CERTIFICATE_VALIDATION = trim( getenv( 'WPT_CERTIFICATE_VALIDATION' ) );
-
-// Configure debug mode based on the WPT_DEBUG environment variable.
-$WPT_DEBUG_INI = getenv( 'WPT_DEBUG' );
-switch( $WPT_DEBUG_INI ) {
-	case 0:
-	case 'false':
-		$WPT_DEBUG = false;
-		break;
-	case 1:
-	case 'true':
-	case 'verbose':
-		$WPT_DEBUG = 'verbose';
-		break;
-	default:
-		$WPT_DEBUG = false;
-		break;
-}
-unset( $WPT_DEBUG_INI );
+$runner_vars = setup_runner_env_vars();
 
 /*
  * Configure a private SSH key for remote testing.
@@ -85,15 +59,15 @@
 	// When am SSH connection string is not provided, add a local operation to the array.
 	// When an SSH connection string is provided, add a remote operation to the array.
 	// Execute the operations defined in the operations array.
-	if( empty( $WPT_SSH_CONNECT ) ) {
+	if( empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
 		perform_operations( array(
 			'chmod 600 ~/.ssh/id_rsa',
 			'wp cli info'
 		) );
 	} else {
 		perform_operations( array(
 			'chmod 600 ~/.ssh/id_rsa',
-			'ssh -q ' . $WPT_SSH_OPTIONS . ' ' . escapeshellarg( $WPT_SSH_CONNECT ) . ' wp cli info'
+			'ssh -q ' . $runner_vars['WPT_SSH_OPTIONS'] . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] ) . ' wp cli info'
 		) );
 	}
 
@@ -104,7 +78,7 @@
  * Useful for local environments
  */
 $certificate_validation = '';
-if( ! $WPT_CERTIFICATE_VALIDATION ) {
+if( ! $runner_vars['WPT_CERTIFICATE_VALIDATION'] ) {
 	$certificate_validation .= ' --no-check-certificate';
 }
 
@@ -120,22 +94,22 @@
 perform_operations( array(
 
 	// Create the preparation directory if it doesn't exist. The '-p' flag creates intermediate directories as required.
-	'mkdir -p ' . escapeshellarg( $WPT_PREPARE_DIR ),
+	'mkdir -p ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] ),
 
 	// Clone the WordPress develop repository from GitHub into the preparation directory.
 	// The '--depth=1' flag creates a shallow clone with a history truncated to the last commit.
-	'git clone --depth=1 https://github.com/WordPress/wordpress-develop.git ' . escapeshellarg( $WPT_PREPARE_DIR ),
+	'git clone --depth=1 https://github.com/WordPress/wordpress-develop.git ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] ),
 
 	// Change directory to the preparation directory, install npm dependencies, and build the project.
-	'cd ' . escapeshellarg( $WPT_PREPARE_DIR ) . '; npm install && npm run build'
+	'cd ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] ) . '; npm install && npm run build'
 
 ) );
 
 // Log a message indicating the start of the variable replacement process for configuration.
 log_message( 'Replacing variables in wp-tests-config.php' );
 
 // Don't validate the TLS certificate. Useful for local environments.
-$contents = file_get_contents( $WPT_PREPARE_DIR . '/wp-tests-config-sample.php' );
+$contents = file_get_contents( $runner_vars['WPT_PREPARE_DIR'] . '/wp-tests-config-sample.php' );
 
 /*
  * Prepare a script for logging system information.
@@ -250,7 +224,7 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
 $system_logger = $logger_replace_string . $system_logger;
 
 // Define a string that will set the 'WP_PHP_BINARY' constant to the path of the PHP executable.
-$php_binary_string = 'define( \'WP_PHP_BINARY\', \''. $WPT_PHP_EXECUTABLE . '\' );';
+$php_binary_string = 'define( \'WP_PHP_BINARY\', \''. $runner_vars['WPT_PHP_EXECUTABLE'] . '\' );';
 
 /*
  * Map configuration file placeholders to environment-specific values.
@@ -272,21 +246,21 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
 $contents = str_replace( array_keys( $search_replace ), array_values( $search_replace ), $contents );
 
 // Write the modified content to the wp-tests-config.php file, which will be used by the test suite.
-file_put_contents( $WPT_PREPARE_DIR . '/wp-tests-config.php', $contents );
+file_put_contents( $runner_vars['WPT_PREPARE_DIR'] . '/wp-tests-config.php', $contents );
 
 /*
  * Construct a command that generates a PHP version string compatible with
  * PHPUnit version requirements.
  */
-$php_version_cmd = $WPT_PHP_EXECUTABLE . " -r \"print PHP_MAJOR_VERSION . '.' . PHP_MINOR_VERSION . '.' . PHP_RELEASE_VERSION;\"";
+$php_version_cmd = $runner_vars['WPT_PHP_EXECUTABLE'] . " -r \"print PHP_MAJOR_VERSION . '.' . PHP_MINOR_VERSION . '.' . PHP_RELEASE_VERSION;\"";
 
 /**
  * This command will differ when running on a remote server via SSH.
  */
-if ( ! empty( $WPT_SSH_CONNECT ) ) {
+if ( ! empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
 	// The PHP version check command is prefixed with the SSH command, including SSH options,
 	// and the connection string, ensuring the command is executed on the remote machine.
-	$php_version_cmd = 'ssh ' . $WPT_SSH_OPTIONS . ' ' . escapeshellarg( $WPT_SSH_CONNECT ) . ' ' . escapeshellarg( $php_version_cmd );
+	$php_version_cmd = 'ssh ' . $runner_vars['WPT_SSH_OPTIONS'] . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] ) . ' ' . escapeshellarg( $php_version_cmd );
 }
 
 // Initialize return value variable for the exec function call.
@@ -322,7 +296,7 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
 
 
 // Check if Composer is installed and available in the PATH.
-$composer_cmd = 'cd ' . escapeshellarg( $WPT_PREPARE_DIR ) . ' && ';
+$composer_cmd = 'cd ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] ) . ' && ';
 $retval = 0;
 $composer_path = escapeshellarg( system( 'which composer', $retval ) );
 
@@ -337,7 +311,7 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
 	log_message( 'Local Composer not found. Downloading latest stable ...' );
 
 	perform_operations( array(
-		'wget -O ' . escapeshellarg( $WPT_PREPARE_DIR . '/composer.phar' ) . ' https://getcomposer.org/composer-stable.phar',
+		'wget -O ' . escapeshellarg( $runner_vars['WPT_PREPARE_DIR'] . '/composer.phar' ) . ' https://getcomposer.org/composer-stable.phar',
 	) );
 
 	// Update the command to use the downloaded Composer phar file.
@@ -359,20 +333,20 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
  * The -r option for rsync enables recursive copying to handle nested directory
  * structures.
  */
-if ( ! empty( $WPT_SSH_CONNECT ) ) {
+if ( ! empty( $runner_vars['WPT_SSH_CONNECT'] ) ) {
 	// Initialize rsync options with recursive copying.
 	$rsync_options = '-r';
 
 	// If debug mode is set to verbose, append 'v' to rsync options for verbose output.
-	if ( 'verbose' === $WPT_DEBUG ) {
+	if ( $runner_vars['WPT_DEBUG'] ) {
 		$rsync_options = $rsync_options . 'v';
 	}
 
 	// Perform the rsync operation with the configured options and exclude patterns.
 	// This operation synchronizes the test environment with the prepared files, excluding version control directories
 	// and other non-essential files for test execution.
 	perform_operations( array(
-		'rsync ' . $rsync_options . ' --exclude=".git/" --exclude="node_modules/" --exclude="composer.phar" -e "ssh ' . $WPT_SSH_OPTIONS . '" ' . escapeshellarg( trailingslashit( $WPT_PREPARE_DIR )  ) . ' ' . escapeshellarg( $WPT_SSH_CONNECT . ':' . $WPT_TEST_DIR ),
+		'rsync ' . $rsync_options . ' --exclude=".git/" --exclude="node_modules/" --exclude="composer.phar" -e "ssh ' . $runner_vars['WPT_SSH_OPTIONS'] . '" ' . escapeshellarg( trailingslashit( $runner_vars['WPT_PREPARE_DIR'] )  ) . ' ' . escapeshellarg( $runner_vars['WPT_SSH_CONNECT'] . ':' . $runner_vars['WPT_TEST_DIR'] ),
 	) );
 }