Merge branch 'javiercasares-report' into javiercasares-prepare

Author: javiercasares

cleanup.php

@@ -1,30 +1,52 @@
 <?php
 
 /**
- * Cleans up the environment after the test run.
+ * 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 required environment variables.
+/**
+ * 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.
+ */
 check_required_env();
 
-// Bring some environment variables into scope.
-$WPT_PREPARE_DIR = getenv( 'WPT_PREPARE_DIR' );
-$WPT_SSH_CONNECT = getenv( 'WPT_SSH_CONNECT' );
-$WPT_SSH_OPTIONS = getenv( 'WPT_SSH_OPTIONS' ) ? : '-o StrictHostKeyChecking=no';
-$WPT_TEST_DIR = getenv( 'WPT_TEST_DIR' );
-$WPT_RM_TEST_DIR_CMD = getenv( 'WPT_RM_TEST_DIR_CMD' ) ? : 'rm -r ' . $WPT_TEST_DIR;
+/**
+ * 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.
+ */
+$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;
 
-// Clean up the preparation directory.
-// Only forcefully delete the .git directory, to prevent disasters otherwise.
+/**
+ * The directory path of the test preparation directory is assumed to be previously defined.
+ * For example: $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 ),
 ) );
 
-// Clean up the test directory in remote environments.
+/**
+ * Cleans up the test directory on a remote server.
+ * This conditional block checks if an SSH connection string is provided and is not empty.
+ * If a connection string is present, it triggers a cleanup operation on the remote environment.
+ * 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 ) ) {
 	perform_operations( array(
 		'ssh ' . $WPT_SSH_OPTIONS . ' ' . escapeshellarg( $WPT_SSH_CONNECT ) . ' ' . escapeshellarg( $WPT_RM_TEST_DIR_CMD ),

prepare.php

@@ -6,6 +6,7 @@
  * The script assumes that certain environment variables are set to configure SSH,
  * directories, and executables used in the test preparation process.
  *
+ * @link https://github.com/wordpress/phpunit-test-runner/ Original source repository
  * @package WordPress
  */
 require __DIR__ . '/functions.php';
@@ -42,6 +43,9 @@
 	case 'true':
 		$WPT_DEBUG = true;
 		break;
+	case 'verbose':
+		$WPT_DEBUG = 'verbose';
+		break;
 	default:
 		$WPT_DEBUG = false;
 		break;
@@ -83,12 +87,12 @@
 	if( empty( $WPT_SSH_CONNECT ) ) {
 		perform_operations( array(
 			'chmod 600 ~/.ssh/id_rsa',
-			'wp cli info',
+			'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 ' . $WPT_SSH_OPTIONS . ' ' . escapeshellarg( $WPT_SSH_CONNECT ) . ' wp cli info'
 		) );
 	}
 
@@ -115,7 +119,7 @@
 	'cd ' . escapeshellarg( $WPT_PREPARE_DIR . '/tests/phpunit/data/plugins/' ) . '; unzip wordpress-importer.zip; rm wordpress-importer.zip',
 
 	// 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( $WPT_PREPARE_DIR ) . '; npm install && npm run build'
 
 ) );
 
@@ -277,21 +281,7 @@
 }
 
 // Log the obtained PHP version for confirmation and debugging purposes.
-log_message( "Environment PHP Version: $env_php_version" );
-
-
-/**
- * Ensures compatibility with PHPUnit by adjusting the PHP version if needed.
- * If the environment's PHP version is 8.x.x, it overrides the version to 7.4.
- * This is because the core PHPUnit tests may not be compatible with PHP 8.x.x.
- */
-if ( substr( $env_php_version, 0 , 2 ) === '8.' ) {
-	// Log the occurrence of PHP version 8.x.x and the decision to use PHPUnit compatible with PHP 7.4 instead.
-	log_message( 'Version 8.x.x Found. Downloading PHPUnit for PHP 7.4 instead for compatibility.' );
-
-	// Override the PHP version to 7.4 for PHPUnit compatibility.
-	$env_php_version = '7.4';
-}
+log_message( 'Environment PHP Version: ' . $env_php_version );
 
 /**
  * Checks if the detected PHP version is below 7.0.
@@ -300,57 +290,43 @@
  */
 if ( version_compare( $env_php_version, '7.0', '<' ) ) {
 	// Logs an error message indicating the test runner's incompatibility with PHP versions below 7.0.
-	error_message( "The test runner is not compatible with PHP < 7.0." );
+	error_message( 'The test runner is not compatible with PHP < 7.0.' );
 }
 
 /**
- * Installs PHPUnit 5.7 directly if the PHP version is less than 7.1.
- * PHPUnit 5.7 is the last version to support PHP 7.0.
+ * Use Composer to manage PHPUnit and its dependencies.
+ * This allows for better dependency management and compatibility.
  */
-if ( version_compare( $env_php_version, '7.1', '<' ) ) {
-
-	// Download the PHPUnit phar file directly using wget.
-	perform_operations( array(
-		'wget -O ' .  escapeshellarg( $WPT_PREPARE_DIR . '/phpunit.phar' ) . ' https://phar.phpunit.de/phpunit-5.7.phar',
-	) );
-
-} else {
-
-	/**
-	 * If the PHP version is 7.1 or greater, use Composer to manage PHPUnit and its dependencies.
-	 * This allows for better dependency management and compatibility.
-	 */
 
-	// Check if Composer is installed and available in the PATH.
-	$composer_cmd = 'cd ' . escapeshellarg( $WPT_PREPARE_DIR ) . ' && ';
-	$retval = 0;
-	$composer_path = escapeshellarg( system( 'which composer', $retval ) );
-
-	if ( $retval === 0 ) {
-
-		// If Composer is available, prepare the command to use the Composer binary.
-		$composer_cmd .= $composer_path . ' ';
+// Check if Composer is installed and available in the PATH.
+$composer_cmd = 'cd ' . escapeshellarg( $WPT_PREPARE_DIR ) . ' && ';
+$retval = 0;
+$composer_path = escapeshellarg( system( 'which composer', $retval ) );
 
-	} else {
+if ( $retval === 0 ) {
 
-		// If Composer is not available, download the Composer phar file.
-		log_message( 'Local Composer not found. Downloading latest stable ...' );
+	// If Composer is available, prepare the command to use the Composer binary.
+	$composer_cmd .= $composer_path . ' ';
 
-		perform_operations( array(
-			'wget -O ' . escapeshellarg( $WPT_PREPARE_DIR . '/composer.phar' ) . ' https://getcomposer.org/composer-stable.phar',
-		) );
+} else {
 
-		// Update the command to use the downloaded Composer phar file.
-		$composer_cmd .= 'php composer.phar ';
-	}
+	// If Composer is not available, download the Composer phar file.
+	log_message( 'Local Composer not found. Downloading latest stable ...' );
 
-	// Set the PHP version for Composer to ensure compatibility and update dependencies.
 	perform_operations( array(
-		$composer_cmd . 'config platform.php ' . escapeshellarg( $env_php_version ),
-		$composer_cmd . 'update',
+		'wget -O ' . escapeshellarg( $WPT_PREPARE_DIR . '/composer.phar' ) . ' https://getcomposer.org/composer-stable.phar',
 	) );
+
+	// Update the command to use the downloaded Composer phar file.
+	$composer_cmd .= 'php composer.phar ';
 }
 
+// Set the PHP version for Composer to ensure compatibility and update dependencies.
+perform_operations( array(
+	$composer_cmd . 'config platform.php ' . escapeshellarg( $env_php_version ),
+	$composer_cmd . 'update',
+) );
+
 /**
  * If an SSH connection is configured, use rsync to transfer the prepared files to the remote test environment.
  * The -r option for rsync enables recursive copying to handle directory structures.