Tests: polyfill select PHPUnit 8.4 functions

Use a trait to selectively polyfill a number of methods introduced in PHPUnit 8.4.

These new PHPUnit methods replace the use of the `expectException()` et al methods to test for expected PHP native errors, warnings and notices.

The old manner of testing these is soft deprecated as of PHPUnit  8.4, hard deprecated as of PHPUnit 9.0 and will be removed in PHPUnit 10.0.0.

The trait contains the complete set  of methods related to this change.

The polyfill methods themselves are effectively just a placeholder/wrapper, they will use the PHPUnit native functions to execute the assertions.

With the polyfill in place, the WP test suite can already be upgraded to use the _current_ way of expecting PHP native errors/warnings/notices.

Once the need to support PHPUnit < 8.4 is dropped, the polyfill can be removed and that is all that is needed at that time.

Ref:
* https://github.com/sebastianbergmann/phpunit/blob/8.4.3/ChangeLog-8.4.md#840---2019-10-04
* sebastianbergmann/phpunit#3775

phpcs.xml.dist

@@ -313,10 +313,19 @@
 	<!-- Exclude the unit tests from select sniffs. -->
 	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
 		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
+		<exclude-pattern>/tests/phpunit/includes/phpunit-polyfills/*</exclude-pattern>
 	</rule>
 	<rule ref="PEAR.NamingConventions.ValidClassName.Invalid">
 		<exclude-pattern>/tests/phpunit/tests/*</exclude-pattern>
 	</rule>
+	<rule ref="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid">
+		<!-- These methods have to be called the same as the PHPUnit native methods. -->
+		<exclude-pattern>/tests/phpunit/includes/phpunit-polyfills/*</exclude-pattern>
+	</rule>
+	<rule ref="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase">
+		<!-- These methods should have the same parameter names the PHPUnit native methods. -->
+		<exclude-pattern>/tests/phpunit/includes/phpunit-polyfills/*</exclude-pattern>
+	</rule>
 
 	<!-- Exclude some old classes that can't be renamed, as it would break back compat. -->
 	<rule ref="PEAR.NamingConventions.ValidClassName.Invalid">

tests/phpunit/includes/bootstrap.php

@@ -160,6 +160,8 @@ function wp_tests_options( $value ) {
 // Delete any default posts & related data.
 _delete_all_posts();
 
+require_once __DIR__ . '/phpunit-polyfills/PHPUnitLessThan840.php';
+
 require_once __DIR__ . '/abstract-testcase.php';
 require_once __DIR__ . '/testcase.php';
 require __DIR__ . '/testcase-rest-api.php';

tests/phpunit/includes/phpunit-polyfills/PHPUnitLessThan840.php

@@ -0,0 +1,151 @@
+<?php
+
+use PHPUnit\Framework\Error\Deprecated;
+use PHPUnit\Framework\Error\Error;
+use PHPUnit\Framework\Error\Notice;
+use PHPUnit\Framework\Error\Warning;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Polyfills select PHPUnit functionality introduced in PHPUnit 8.4.0 to older PHPUnit versions.
+ *
+ * When the minimum supported PHPUnit version of the WP testsuite goes
+ * beyond PHPUnit 8.4.0, this polyfill trait can be removed.
+ *
+ * @since 5.6.0
+ */
+trait PHPUnitLessThan840 {
+
+	public function expectDeprecation(): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectDeprecation' ) ) ) {
+			TestCase::expectDeprecation();
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectException( Deprecated::class );
+	}
+
+	public function expectDeprecationMessage( string $message ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectDeprecationMessage' ) ) ) {
+			TestCase::expectDeprecationMessage( $message );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessage( $message );
+	}
+
+	public function expectDeprecationMessageMatches( string $regularExpression ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectDeprecationMessageMatches' ) ) ) {
+			TestCase::expectDeprecationMessageMatches( $regularExpression );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessageRegExp( $regularExpression );
+	}
+
+	public function expectNotice(): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectNotice' ) ) ) {
+			TestCase::expectNotice();
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectException( Notice::class );
+	}
+
+	public function expectNoticeMessage( string $message ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectNoticeMessage' ) ) ) {
+			TestCase::expectNoticeMessage( $message );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessage( $message );
+	}
+
+	public function expectNoticeMessageMatches( string $regularExpression ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectNoticeMessageMatches' ) ) ) {
+			TestCase::expectNoticeMessageMatches( $regularExpression );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessageRegExp( $regularExpression );
+	}
+
+	public function expectWarning(): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectWarning' ) ) ) {
+			TestCase::expectWarning();
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectException( Warning::class );
+	}
+
+	public function expectWarningMessage( string $message ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectWarningMessage' ) ) ) {
+			TestCase::expectWarningMessage( $message );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessage( $message );
+	}
+
+	public function expectWarningMessageMatches( string $regularExpression ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectWarningMessageMatches' ) ) ) {
+			TestCase::expectWarningMessageMatches( $regularExpression );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessageRegExp( $regularExpression );
+	}
+
+	public function expectError(): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectError' ) ) ) {
+			TestCase::expectError();
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectException( Error::class );
+	}
+
+	public function expectErrorMessage( string $message ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectErrorMessage' ) ) ) {
+			TestCase::expectErrorMessage( $message );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessage( $message );
+	}
+
+	public function expectErrorMessageMatches( string $regularExpression ): void {
+		// PHPUnit >= 8.4.0: Use the PHPUnit native method.
+		if ( is_callable( array( TestCase::class, 'expectErrorMessageMatches' ) ) ) {
+			TestCase::expectErrorMessageMatches( $regularExpression );
+			return;
+		}
+
+		// PHPUnit < 8.4.0.
+		$this->expectExceptionMessageRegExp( $regularExpression );
+	}
+
+}

tests/phpunit/includes/testcase.php

@@ -9,4 +9,8 @@
  *
  * All WordPress unit tests should inherit from this class.
  */
-class WP_UnitTestCase extends WP_UnitTestCase_Base {}
+class WP_UnitTestCase extends WP_UnitTestCase_Base {
+
+	use PHPUnitLessThan840;
+
+}