Add WP_CLI_TEST_XDEBUG environment variable to enable Xdebug step debugging in Behat tests

Co-authored-by: swissspidy <[email protected]>

Author: Copilot

README.md

@@ -147,6 +147,23 @@ chmod +x ~/wp-cli/wp
 WP_CLI_BIN_DIR=~/wp-cli composer behat
 ```
 
+#### Xdebug Step Debugging
+
+You can enable Xdebug step debugging for Behat tests by setting the `WP_CLI_TEST_XDEBUG` environment variable.
+
+This is useful when you want to debug the actual WP-CLI + WordPress code that is being run during the tests.
+
+```bash
+WP_CLI_TEST_XDEBUG=true composer behat
+```
+
+This will set the following Xdebug environment variables for all WP-CLI processes spawned by the tests:
+- `XDEBUG_MODE=debug`
+- `XDEBUG_SESSION=1`
+- `XDEBUG_CONFIG="idekey=WP_CLI_TEST_XDEBUG log_level=0"`
+
+Note: You need to have Xdebug installed and your IDE configured to listen for debug connections.
+
 ### Setting up the tests in Travis CI
 
 Basic rules for setting up the test framework with Travis CI:

src/Context/FeatureContext.php

@@ -282,6 +282,17 @@ private static function running_with_code_coverage() {
 		return \in_array( $with_code_coverage, [ 'true', '1' ], true );
 	}
 
+	/**
+	 * Whether tests are currently running with Xdebug step debugging enabled.
+	 *
+	 * @return bool
+	 */
+	private static function running_with_xdebug() {
+		$with_xdebug = (string) getenv( 'WP_CLI_TEST_XDEBUG' );
+
+		return \in_array( $with_xdebug, [ 'true', '1' ], true );
+	}
+
 	/**
 	 * @AfterSuite
 	 */
@@ -466,6 +477,12 @@ private static function get_process_env_variables(): array {
 			$env['WP_CLI_REQUIRE'] = $updated;
 		}
 
+		if ( self::running_with_xdebug() ) {
+			$env['XDEBUG_MODE']    = 'debug';
+			$env['XDEBUG_SESSION'] = '1';
+			$env['XDEBUG_CONFIG']  = 'idekey=WP_CLI_TEST_XDEBUG log_level=0';
+		}
+
 		$config_path = getenv( 'WP_CLI_CONFIG_PATH' );
 		if ( false !== $config_path ) {
 			$env['WP_CLI_CONFIG_PATH'] = $config_path;