Add WP_CLI_TEST_XDEBUG environment variable for step debugging in Behat tests

README.md

@@ -176,6 +176,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

@@ -308,6 +308,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;
@@ -506,6 +517,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;