Polyfill for equalTo constraint specializations

README.md

@@ -359,6 +359,16 @@ These methods were introduced in PHPUnit 8.5.0 as alternatives to using `Assert:
 COMMENT: No documentation available (yet) for these assertions on the PHPUnit site.
 -->
 
+#### PHPUnit < 9.0.0: `Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations`
+
+Polyfills the following methods:
+|                                   |                                 |
+|-----------------------------------|---------------------------------|
+| `Assert::equalToCanonicalizing()` | `Assert::equalToIgnoringCase()` |
+| `Assert::equalToWithDelta()`      |                                 |
+
+These methods, which are typically used to verify parameters passed to Mock Objects, were introduced in PHPUnit 9.0.0 as alternatives to using `Assert::EqualTo()` with these optional parameters. Support for passing the respective optional parameters to `Assert::EqualTo()` was removed in PHPUnit 9.0.0.
+
 #### PHPUnit < 9.1.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertionRenames`
 
 Polyfills the following renamed methods:

phpunitpolyfills-autoload.php

@@ -65,6 +65,10 @@ public static function load( $className ) {
 					self::loadAssertFileEqualsSpecializations();
 					return true;
 
+				case 'Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations':
+					self::loadEqualToSpecializations();
+					return true;
+
 				case 'Yoast\PHPUnitPolyfills\Polyfills\AssertionRenames':
 					self::loadAssertionRenames();
 					return true;
@@ -324,6 +328,23 @@ public static function loadAssertFileEqualsSpecializations() {
 			require_once __DIR__ . '/src/Polyfills/AssertFileEqualsSpecializations_Empty.php';
 		}
 
+		/**
+		 * Load the EqualToSpecializations polyfill or an empty trait with the same name
+		 * if a PHPUnit version is used which already contains this functionality.
+		 *
+		 * @return void
+		 */
+		public static function loadEqualToSpecializations() {
+			if ( \method_exists( '\PHPUnit\Framework\Assert', 'equalToWithDelta' ) === false ) {
+				// PHPUnit < 9.0.0.
+				require_once __DIR__ . '/src/Polyfills/EqualToSpecializations.php';
+				return;
+			}
+
+			// PHPUnit >= 9.0.0.
+			require_once __DIR__ . '/src/Polyfills/EqualToSpecializations_Empty.php';
+		}
+
 		/**
 		 * Load the AssertionRenames polyfill or an empty trait with the same name
 		 * if a PHPUnit version is used which already contains this functionality.

src/Polyfills/EqualToSpecializations.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Yoast\PHPUnitPolyfills\Polyfills;
+
+use PHPUnit\Framework\Constraint\IsEqual;
+
+/**
+ * Polyfill the Assert::equalToCanonicalizing(), Assert::equalToIgnoringCase() and
+ * Assert::equalToWithDelta(), which replace the use of Assert::equalTo()
+ * with these optional parameters.
+ *
+ * Introduced in PHPUnit 9.0.0.
+ * Use of Assert::equalTo() with these respective optional parameters was
+ * never deprecated but leads to unexpected behaviour as they are ignored in PHPUnit 9.0.0.
+ *
+ * @link https://github.com/sebastianbergmann/phpunit/commit/43c01a4e0c74a4bf019a8d879bced5146af2fbb6
+ */
+trait EqualToSpecializations {
+
+	/**
+	 * Creates "is equal" constraint (canonicalizing).
+	 *
+	 * @param mixed $value Expected value for constraint.
+	 *
+	 * @return IsEqual|PHPUnit_Framework_Constraint_IsEqual An isEqual constraint instance.
+	 */
+	public static function equalToCanonicalizing( $value ) {
+		return static::equalTo( $value, 0.0, 10, true, false );
+	}
+
+	/**
+	 * Creates "is equal" constraint (ignoring case).
+	 *
+	 * @param mixed $value Expected value for constraint.
+	 *
+	 * @return IsEqual|PHPUnit_Framework_Constraint_IsEqual An isEqual constraint instance.
+	 */
+	public static function equalToIgnoringCase( $value ) {
+		return static::equalTo( $value, 0.0, 10, false, true );
+	}
+
+	/**
+	 * Creates "is equal" constraint (with delta).
+	 *
+	 * @param mixed $value Expected value for constraint.
+	 * @param float $delta The delta to allow between the expected and the actual value.
+	 *
+	 * @return IsEqual|PHPUnit_Framework_Constraint_IsEqual An isEqual constraint instance.
+	 */
+	public static function equalToWithDelta( $value, $delta ) {
+		return static::equalTo( $value, $delta, 10, false, false );
+	}
+}

src/Polyfills/EqualToSpecializations_Empty.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Yoast\PHPUnitPolyfills\Polyfills;
+
+/**
+ * Empty trait for use with PHPUnit >= 9.0.0 in which this polyfill is not needed.
+ */
+trait EqualToSpecializations {}

src/TestCases/TestCasePHPUnitGte8.php

@@ -7,6 +7,7 @@
 use Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertFileEqualsSpecializations;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertionRenames;
+use Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectPHPException;
 
@@ -25,6 +26,7 @@ abstract class TestCase extends PHPUnit_TestCase {
 	use AssertClosedResource;
 	use AssertFileEqualsSpecializations;
 	use AssertionRenames;
+	use EqualToSpecializations;
 	use ExpectExceptionMessageMatches;
 	use ExpectPHPException;
 

src/TestCases/TestCasePHPUnitLte7.php

@@ -12,6 +12,7 @@
 use Yoast\PHPUnitPolyfills\Polyfills\AssertIsType;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertNumericType;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains;
+use Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectException;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionObject;
@@ -37,6 +38,7 @@ abstract class TestCase extends PHPUnit_TestCase {
 	use AssertIsType;
 	use AssertNumericType;
 	use AssertStringContains;
+	use EqualToSpecializations;
 	use ExpectException;
 	use ExpectExceptionMessageMatches;
 	use ExpectExceptionObject;

src/TestCases/XTestCase.php

@@ -12,6 +12,7 @@
 use Yoast\PHPUnitPolyfills\Polyfills\AssertIsType;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertNumericType;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains;
+use Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectException;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionObject;
@@ -39,6 +40,7 @@ abstract class XTestCase extends PHPUnit_TestCase {
 	use AssertIsType;
 	use AssertNumericType;
 	use AssertStringContains;
+	use EqualToSpecializations;
 	use ExpectException;
 	use ExpectExceptionMessageMatches;
 	use ExpectExceptionObject;

tests/Polyfills/EqualToSpecializationsTest.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Yoast\PHPUnitPolyfills\Tests\Polyfills;
+
+use PHPUnit\Framework\TestCase;
+use Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations;
+
+/**
+ * Availability test for the functions polyfilled by the EqualToSpecializations trait.
+ *
+ * @covers \Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations
+ */
+class EqualToSpecializationsTest extends TestCase {
+
+	use EqualToSpecializations;
+
+	/**
+	 * Verify availability of the equalToWithDelta() method.
+	 *
+	 * @return void
+	 */
+	public function testEqualToWithDelta() {
+		$this->assertThat( 2.5, $this->equalToWithDelta( 2.3, 0.5 ) );
+	}
+
+	/**
+	 * Verify availability of the equalToCanonicalizing() method.
+	 *
+	 * @return void
+	 */
+	public function testEqualToCanonicalizing() {
+		self::assertThat( [ 2, 3, 1 ], static::equalToCanonicalizing( [ 3, 2, 1 ] ) );
+	}
+
+	/**
+	 * Verify availability of the equalIgnoringCase() method.
+	 *
+	 * @return void
+	 */
+	public function testEqualToIgnoringCase() {
+		self::assertThat( 'A', self::equalToIgnoringCase( 'a' ) );
+	}
+
+	/**
+	 * Verify ability of the equalToWithDelta() method to correctly fail a comparison.
+	 *
+	 * @return void
+	 */
+	public function testEqualToWithDeltaNegative() {
+		self::assertThat( 3.5, $this->logicalNot( $this->equalToWithDelta( 2.3, 0.5 ) ) );
+	}
+
+	/**
+	 * Verify ability of the equalToCanonicalizing() method to correctly fail a comparison.
+	 *
+	 * @return void
+	 */
+	public function testEqualToCanonicalizingNegative() {
+		static::assertThat( [ 2, 3, 1 ], $this->logicalNot( static::equalToCanonicalizing( [ 4, 2, 1 ] ) ) );
+	}
+
+	/**
+	 * Verify ability of the equalToIgnoringCaseNegative() method to correctly fail a comparison.
+	 *
+	 * @return void
+	 */
+	public function testEqualToIgnoringCaseNegative() {
+		self::assertThat( 'A', $this->logicalNot( $this->equalToIgnoringCase( 'b' ) ) );
+	}
+}

tests/TestCases/TestCaseTestTrait.php

@@ -154,4 +154,13 @@ public function testAvailabilityAssertClosedResource() {
 
 		$this->assertIsClosedResource( $resource );
 	}
+
+	/**
+	 * Verify availability of trait polyfilled PHPUnit methods [13].
+	 *
+	 * @return void
+	 */
+	public function testAvailabilityEqualToSpecializations() {
+		self::assertThat( [ 2, 3, 1 ], $this->equalToCanonicalizing( [ 3, 2, 1 ] ) );
+	}
 }