Create helper function for parsing runner configuration environment variables

.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

cleanup.php

@@ -16,27 +16,21 @@
 check_required_env();
 
 /**
- * Retrieves environment variables and sets defaults for test preparation.
- * 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();
 
 /**
  * The directory path of the test preparation directory is assumed to be previously defined.
- * For example: $WPT_PREPARE_DIR = '/path/to/your/preparation/dir';
+ * For example: $runner_vars['WPT_PREPARE_DIR'] = '/path/to/your/preparation/dir';
  * Clean up the preparation directory.
  * Forcefully deletes only the .git directory and the node_modules cache.
  * Afterward, the entire preparation directory is removed to ensure a clean state for the next test run.
  */
 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'] ),
 ) );
 
 /**
@@ -46,8 +40,8 @@
  * The cleanup operation is executed by the `perform_operations` function which takes an array
  * of shell commands as its input.
  */
-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

@@ -43,6 +43,67 @@ 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 series of shell commands provided in the operations array. Each operation is logged before execution.
  * If any command fails (indicated by a non-zero return code), an error message is displayed. This function is

prepare.php

@@ -18,37 +18,9 @@
 check_required_env();
 
 /**
- * Retrieves environment variables and sets defaults for test preparation.
- * 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' ) );
-
-/**
- * Determines if the debug mode is enabled based on the 'WPT_DEBUG' environment variable.
- * The debug mode can affect error reporting and other debug-related settings.
- */
-$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();
 
 /**
  * Sets up the SSH private key for use in the test environment if provided.
@@ -82,15 +54,15 @@
 	// If no SSH connection string is provided, add a local operation to the array.
 	// If 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'
 		) );
 	}
 
@@ -101,7 +73,7 @@
  * Useful for local environments
  */
 $certificate_validation = '';
-if( ! $WPT_CERTIFICATE_VALIDATION ) {
+if( ! $runner_vars['WPT_CERTIFICATE_VALIDATION'] ) {
 	$certificate_validation .= ' --no-check-certificate';
 }
 
@@ -113,14 +85,14 @@
 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'
 
 ) );
 
@@ -132,7 +104,7 @@
  * This file contains template placeholders that need to be replaced with actual values 
  * from environment variables to configure the WordPress test environment.
  */
-$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' );
 
 /**
  * Prepares a script to log system information relevant to the testing environment.
@@ -240,7 +212,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'] . '\' );';
 
 /**
  * An associative array mapping configuration file placeholders to environment-specific values.
@@ -261,22 +233,22 @@ 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 );
 
 /**
  * Determines the PHP version of the test environment to ensure the correct version of PHPUnit is installed.
  * It constructs a command that prints out the PHP version in a format compatible with PHPUnit's 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;\"";
 
 /**
  * If an SSH connection string is provided, the command to determine the PHP version is modified 
  * to execute remotely over SSH. This is required if the test environment is not the local machine.
  */
-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.
@@ -313,7 +285,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 ) );
 
@@ -328,7 +300,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.
@@ -346,20 +318,20 @@ function curl_selected_bits(\$k) { return in_array(\$k, array('version', 'ssl_ve
  * The -r option for rsync enables recursive copying to handle directory structures.
  * Additional rsync options may be included for more verbose output if debugging is enabled.
  */
-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'] ),
 	) );
 }