From f802ab2bceb3840ec3dc3113516e7d9163d609f5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 1 Dec 2025 15:29:09 +0000
Subject: [PATCH 1/2] Initial plan


From 21b82d34511bc81bb2096209afc29c1f69b0808e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 1 Dec 2025 16:20:49 +0000
Subject: [PATCH 2/2] Add WP_CLI_TEST_XDEBUG environment variable to enable
 Xdebug step debugging in Behat tests

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 README.md                      | 17 +++++++++++++++++
 src/Context/FeatureContext.php | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/README.md b/README.md
index 3be233521..0003e568a 100644
--- a/README.md
+++ b/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:
diff --git a/src/Context/FeatureContext.php b/src/Context/FeatureContext.php
index 4ec3c15a3..739dd0e29 100644
--- a/src/Context/FeatureContext.php
+++ b/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;