AssertObjectEquals: improve "not boolean return value" error message

... and add tests covering this exception.

Author: jrfnl

.phpcs.xml.dist

@@ -146,7 +146,7 @@
 	</rule>
 
 	<!-- These fixtures for the assertEqualObject() tests will only be loaded on PHP 7+/8+ respectively. -->
-	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.boolFound">
+	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations">
 		<exclude-pattern>/tests/Polyfills/Fixtures/ChildValueObject\.php$</exclude-pattern>
 		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
 		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
@@ -155,5 +155,8 @@
 		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
 		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnionNoReturnType\.php$</exclude-pattern>
 	</rule>
+	<rule ref="PHPCompatibility.Operators.NewOperators.t_spaceshipFound">
+		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
+	</rule>
 
 </ruleset>

src/Polyfills/AssertObjectEquals.php

@@ -212,7 +212,7 @@ public static function assertObjectEquals( $expected, $actual, $method = 'equals
 		if ( \is_bool( $result ) === false ) {
 			throw new InvalidComparisonMethodException(
 				\sprintf(
-					'%s::%s() does not return a boolean value.',
+					'Comparison method %s::%s() does not return a boolean value.',
 					\get_class( $actual ),
 					$method
 				)

tests/Polyfills/AssertObjectEqualsPHPUnitLt940Test.php

@@ -263,6 +263,23 @@ public function testAssertObjectEqualsFailsOnMethodParamTypeMismatch() {
 		$this->assertObjectEquals( new stdClass(), $actual );
 	}
 
+	/**
+	 * Verify that the assertObjectEquals() method throws an error when the declared return type/
+	 * the return value is not boolean.
+	 *
+	 * @return void
+	 */
+	public function testAssertObjectEqualsFailsOnNonBooleanReturnValue() {
+		$msg = 'Comparison method Yoast\PHPUnitPolyfills\Tests\Polyfills\Fixtures\ValueObjectNoReturnType::equalsNonBooleanReturnType() does not return a boolean value.';
+
+		$this->expectException( self::COMPARATOR_EXCEPTION );
+		$this->expectExceptionMessage( $msg );
+
+		$expected = new ValueObjectNoReturnType( 100 );
+		$actual   = new ValueObjectNoReturnType( 100 );
+		$this->assertObjectEquals( $expected, $actual, 'equalsNonBooleanReturnType' );
+	}
+
 	/**
 	 * Verify that the assertObjectEquals() method fails a test when a call to method
 	 * determines that the objects are not equal.

tests/Polyfills/AssertObjectEqualsTest.php

@@ -340,6 +340,30 @@ public function testAssertObjectEqualsFailsOnMethodParamTypeMismatch() {
 		$this->assertObjectEquals( new stdClass(), $actual );
 	}
 
+	/**
+	 * Verify that the assertObjectEquals() method throws an error when the declared return type/
+	 * the return value is not boolean.
+	 *
+	 * @return void
+	 */
+	public function testAssertObjectEqualsFailsOnNonBooleanReturnValue() {
+		$msg = 'Comparison method Yoast\PHPUnitPolyfills\Tests\Polyfills\Fixtures\ValueObject::equalsNonBooleanReturnType() does not return a boolean value.';
+
+		$exception = self::COMPARATOR_EXCEPTION;
+		if ( \class_exists( 'PHPUnit\Framework\ComparisonMethodDoesNotDeclareBoolReturnTypeException' ) ) {
+			// PHPUnit > 9.4.0.
+			$msg       = 'Comparison method Yoast\PHPUnitPolyfills\Tests\Polyfills\Fixtures\ValueObject::equalsNonBooleanReturnType() does not declare bool return type.';
+			$exception = 'PHPUnit\Framework\ComparisonMethodDoesNotDeclareBoolReturnTypeException';
+		}
+
+		$this->expectException( $exception );
+		$this->expectExceptionMessage( $msg );
+
+		$expected = new ValueObject( 100 );
+		$actual   = new ValueObject( 100 );
+		$this->assertObjectEquals( $expected, $actual, 'equalsNonBooleanReturnType' );
+	}
+
 	/**
 	 * Verify that the assertObjectEquals() method fails a test when a call to method
 	 * determines that the objects are not equal.

tests/Polyfills/Fixtures/ValueObject.php

@@ -102,4 +102,15 @@ public function equalsParamNonClassType( array $other ): bool {
 	public function equalsParamNonExistentClassType( ClassWhichDoesntExist $other ): bool {
 		return ( $this->value === $other->value );
 	}
+
+	/**
+	 * Comparator method: incorrectly declared - non-boolean return type/value.
+	 *
+	 * @param self $other Object to compare.
+	 *
+	 * @return bool
+	 */
+	public function equalsNonBooleanReturnType( self $other ): int {
+		return ( $this->value <=> $other->value );
+	}
 }

tests/Polyfills/Fixtures/ValueObjectNoReturnType.php

@@ -102,4 +102,23 @@ public function equalsParamNonClassType( array $other ) {
 	public function equalsParamNonExistentClassType( ClassWhichDoesntExist $other ) {
 		return ( $this->value === $other->value );
 	}
+
+	/**
+	 * Comparator method: incorrectly declared - non-boolean return type/value.
+	 *
+	 * @param self $other Object to compare.
+	 *
+	 * @return int
+	 */
+	public function equalsNonBooleanReturnType( self $other ) {
+		if ( $this->value === $other->value ) {
+			return 0;
+		}
+
+		if ( $this->value > $other->value ) {
+			return 1;
+		}
+
+		return -1;
+	}
 }