Add WP_CLI_TEST_XDEBUG environment variable for step debugging in Behat tests

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

@@ -278,6 +278,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 );
+	}
+
 	public static function merge_coverage_reports(): void {
 		if ( ! self::running_with_code_coverage() ) {
 			return;
@@ -459,6 +470,35 @@ private static function get_process_env_variables(): array {
 			$env['WP_CLI_REQUIRE'] = $updated;
 		}
 
+		if ( self::running_with_xdebug() ) {
+			$xdebug_mode = getenv( 'XDEBUG_MODE' );
+			if ( false !== $xdebug_mode && '' !== $xdebug_mode ) {
+				$modes = array_filter(
+					array_map(
+						'trim',
+						explode( ',', $xdebug_mode )
+					),
+					static function ( $mode ) {
+						return '' !== $mode;
+					}
+				);
+				if ( ! in_array( 'debug', $modes, true ) ) {
+					$modes[] = 'debug';
+				}
+				$env['XDEBUG_MODE'] = implode( ',', $modes );
+			} else {
+				$env['XDEBUG_MODE'] = 'debug';
+			}
+
+			if ( false === getenv( 'XDEBUG_SESSION' ) ) {
+				$env['XDEBUG_SESSION'] = '1';
+			}
+
+			if ( false === getenv( 'XDEBUG_CONFIG' ) ) {
+				$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;