Add diff output for failed Behat comparisons

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

Author: Copilot

composer.json

@@ -20,6 +20,7 @@
         "phpstan/phpstan-deprecation-rules": "^1.2 || ^2.0",
         "phpstan/phpstan-phpunit": "^1.4 || ^2.0",
         "phpstan/phpstan-strict-rules": "^1.6 || ^2.0",
+        "sebastian/diff": "^4.0 || ^5.0 || ^6.0 || ^7.0",
         "swissspidy/phpstan-no-private": "^0.2.1 || ^1.0",
         "szepeviktor/phpstan-wordpress": "^v1.3.5",
         "wp-cli/config-command": "^1 || ^2",

src/Context/Support.php

@@ -8,6 +8,8 @@
 use Behat\Behat\Exception\PendingException;
 use Exception;
 use Mustangostang\Spyc;
+use SebastianBergmann\Diff\Differ;
+use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;
 
 trait Support {
 
@@ -120,6 +122,15 @@ protected function check_string( $output, $expected, $action, $message = false,
 			if ( false === $message ) {
 				$message = $output;
 			}
+
+			// Add diff for 'be' comparisons to show exact differences.
+			if ( 'be' === $action ) {
+				$diff = $this->generate_diff( $expected, rtrim( $output, "\n" ) );
+				if ( ! empty( $diff ) ) {
+					$message .= "\n\n" . $diff;
+				}
+			}
+
 			throw new Exception( $message );
 		}
 	}
@@ -133,15 +144,21 @@ protected function check_string( $output, $expected, $action, $message = false,
 	protected function compare_tables( $expected_rows, $actual_rows, $output ): void {
 		// The first row is the header and must be present.
 		if ( $expected_rows[0] !== $actual_rows[0] ) {
-			throw new Exception( $output );
+			$expected_table = implode( "\n", $expected_rows );
+			$actual_table   = implode( "\n", $actual_rows );
+			$diff           = $this->generate_diff( $expected_table, $actual_table );
+			throw new Exception( $output . "\n\n" . $diff );
 		}
 
 		unset( $actual_rows[0] );
 		unset( $expected_rows[0] );
 
 		$missing_rows = array_diff( $expected_rows, $actual_rows );
 		if ( ! empty( $missing_rows ) ) {
-			throw new Exception( $output );
+			$expected_table = implode( "\n", $expected_rows );
+			$actual_table   = implode( "\n", $actual_rows );
+			$diff           = $this->generate_diff( $expected_table, $actual_table );
+			throw new Exception( $output . "\n\n" . $diff );
 		}
 	}
 
@@ -290,4 +307,20 @@ protected function check_that_yaml_string_contains_yaml_string( $actual_yaml, $e
 
 		return $this->compare_contents( $expected_value, $actual_value );
 	}
+
+	/**
+	 * Generate a unified diff between two strings.
+	 *
+	 * @param string $expected The expected string.
+	 * @param string $actual   The actual string.
+	 * @return string The unified diff output.
+	 */
+	protected function generate_diff( $expected, $actual ) {
+		$builder = new UnifiedDiffOutputBuilder(
+			"--- Expected\n+++ Actual\n",
+			false
+		);
+		$differ  = new Differ( $builder );
+		return $differ->diff( $expected, $actual );
+	}
 }

src/Context/ThenStepDefinitions.php

@@ -215,7 +215,17 @@ public function then_stdout_should_be_json_containing( PyStringNode $expected ):
 		$expected = $this->replace_variables( (string) $expected );
 
 		if ( ! $this->check_that_json_string_contains_json_string( $output, $expected ) ) {
-			throw new Exception( $this->result );
+			$message = (string) $this->result;
+			// Pretty print JSON for better diff readability.
+			$expected_json = json_encode( json_decode( $expected ), JSON_PRETTY_PRINT );
+			$actual_json   = json_encode( json_decode( $output ), JSON_PRETTY_PRINT );
+			if ( $expected_json && $actual_json ) {
+				$diff = $this->generate_diff( $expected_json, $actual_json );
+				if ( ! empty( $diff ) ) {
+					$message .= "\n\n" . $diff;
+				}
+			}
+			throw new Exception( $message );
 		}
 	}
 
@@ -246,7 +256,17 @@ public function then_stdout_should_be_a_json_array_containing( PyStringNode $exp
 
 		$missing = array_diff( $expected_values, $actual_values );
 		if ( ! empty( $missing ) ) {
-			throw new Exception( $this->result );
+			$message = (string) $this->result;
+			// Pretty print JSON arrays for better diff readability.
+			$expected_json = json_encode( $expected_values, JSON_PRETTY_PRINT );
+			$actual_json   = json_encode( $actual_values, JSON_PRETTY_PRINT );
+			if ( $expected_json && $actual_json ) {
+				$diff = $this->generate_diff( $expected_json, $actual_json );
+				if ( ! empty( $diff ) ) {
+					$message .= "\n\n" . $diff;
+				}
+			}
+			throw new Exception( $message );
 		}
 	}
 
@@ -276,7 +296,17 @@ public function then_stdout_should_be_csv_containing( TableNode $expected ): voi
 		}
 
 		if ( ! $this->check_that_csv_string_contains_values( $output, $expected_rows ) ) {
-			throw new Exception( $this->result );
+			$message = (string) $this->result;
+			// Convert expected rows to CSV format for diff.
+			$expected_csv = '';
+			foreach ( $expected_rows as $row ) {
+				$expected_csv .= implode( ',', array_map( 'trim', $row ) ) . "\n";
+			}
+			$diff = $this->generate_diff( trim( $expected_csv ), trim( $output ) );
+			if ( ! empty( $diff ) ) {
+				$message .= "\n\n" . $diff;
+			}
+			throw new Exception( $message );
 		}
 	}
 
@@ -303,7 +333,12 @@ public function then_stdout_should_be_yaml_containing( PyStringNode $expected ):
 		$expected = $this->replace_variables( (string) $expected );
 
 		if ( ! $this->check_that_yaml_string_contains_yaml_string( $output, $expected ) ) {
-			throw new Exception( $this->result );
+			$message = (string) $this->result;
+			$diff    = $this->generate_diff( $expected, $output );
+			if ( ! empty( $diff ) ) {
+				$message .= "\n\n" . $diff;
+			}
+			throw new Exception( $message );
 		}
 	}