-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
PHPUnit 11 | ExpectUserDeprecationtrait: polyfill the TestCase::expec…
…tUserDeprecation*() methods
PHPUnit 11.0.0 introduces the new `TestCase::expectUserDeprecationMessage()` and `TestCase::expectUserDeprecationMessageMatches()` methods.
These methods can largely be seen as replacements for the `TestCase::expectDeprecationMessage()` and `TestCase::expectDeprecationMessageMatches()` methods which were removed in PHPUnit 10.0, though there are significant differences between the implementation details of the old vs the new methods.
As PHPUnit 10 does not have any even semi-equivalent method(s) available, the challenge was to polyfill these methods for PHPUnit 10.
And as these methods are expectation methods, not assertions, this is even more challenging as the information to evaluate a pass/fail is not available at the time of the method call, but only once the rest of the test code has run.
To do so, the following five options were considered:
**Option 1: evaluate pass/fail in an "assertPostConditions()" method**
While possible, doing so would make the use of the `Yoast\PHPUnitPolyfills\TestCases\TestCase` base class required.
It would also mean deprecating/removing the annotation-based `Yoast\PHPUnitPolyfills\TestCases\XTestCase` class as there is no annotation available to mark a method as an "assertPostConditions()" method, so the functionality could not work with the `XTestCase` class.
As a knock-on effect of making the use of the Polyfilled `TestCase` a requirement, it would also mean that using of the individual Polyfills as stand-alone traits should be deprecated/no longer be supported.
This chain of consequences was deemed undesirable as it breaks the premise of the Polyfills being a "drop in" helper library.
**Option 2: use Events to evaluate pass/fail**
While possible, doing so would mean that the event listeners would need to be "hooked in" from the PHPUnit config file.
This would mean that every project using the Polyfills and wanting to use the `expectUserDeprecation*()` methods would need to make changes to their PHPUnit configuration file.
Additionally, adding the event listeners would make a configuration file incompatible with PHPUnit <= 9 and the event listener should not be hooked in for PHPUnit 11, in which the functionality exists in PHPUnit natively. In other words, it would mean that end-users would now need three (3) different PHPUnit configuration files, one for PHPUnit <=9, one for PHPUnit 10 and one for PHPUnit 11.
Again, this was deemed undesirable as it breaks the premise of the Polyfills being a "drop in" helper library.
**Option 3: polyfill, but don't support PHPUnit 10 in the polyfill**
This would basically mean that any test using the `expectUserDeprecation*()` polyfill would be marked as skipped on PHPUnit 10.
This is not a transparent action and the impact of this on tests was deemed too high to be acceptable.
**Option 4: don't polyfill**
It should be obvious that this is the least desirable option as this would mean the polyfills wouldn't polyfill (at least for these methods).
**Option 5: polyfill, but drop support for PHPUnit 10 completely**
This means polyfilling for PHPUnit <= 9 by dropping through to the "old" functions and not supporting installation of the Polyfills 3.x versions in combination with PHPUnit 10.
In practical terms, the net effect of this is that tests on PHP 8.1 would run on PHPUnit 9 instead of PHPUnit 10. Other than that, there is no downside.
Having considered these options carefully, option 5 was deemed most appropriate and most in line with the simple elegance of the functionality offered by the PHPUnit Polyfills until now.
Final note: when falling through to the "old" methods on PHPUnit 9.5.x, PHPUnit native deprecation notices will be shown (but won't fail a build).
Unfortunately, this is unavoidable as the `@` operator is not respected and cannot silence these deprecation notices.
Having said that, as long as the polyfilled methods are used in the actual test suite, these deprecation notices can be safely ignored anyway.
This commit implements option 5:
* Adds two traits with the same name.
One to polyfill the methods when not available in PHPUnit.
The other - an empty trait - to allow for `use`-ing the trait in PHPUnit versions in which the methods are already natively available.
* Adds logic to the custom autoloader which will load the correct trait depending on the PHPUnit version used.
* Adds an availability test for the functionality polyfilled.
* Adds documentation in the `README` about the differences in the functionality of the `expectUserDeprecation*()` methods in PHPUnit <= 9 versus PHPUnit 11.
Includes:
* Adding the new polyfill to the existing `TestCases` classes.
This commit also drops support for PHPUnit 10:
* Make the version drop explicit via the PHPUnit `require` settings in the `composer.json` file.
* Update the GH Actions `test` workflow to no longer run the tests against PHPUnit 10.
This also allows for getting rid of a number of work-arounds which were previously needed for running the tests on both PHPUnit 10.0 and PHPUnit 10.1+.
* Updates the PHPUnit 10+ configuration file used by the polyfills package itself to the schema supported in PHPUnit 11.
This includes adding some configuration options to the file, which were previously, conditionally, added in the CI run as those options were not available in PHPUnit 10.0.
Refs:
* sebastianbergmann/phpunit 5605- Loading branch information
Showing
13 changed files
with
199 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| <?php | ||
|
|
||
| namespace Yoast\PHPUnitPolyfills\Polyfills; | ||
|
|
||
| use PHPUnit\Framework\Error\Deprecated; | ||
| use PHPUnit\Framework\TestCase; | ||
|
|
||
| /** | ||
| * Polyfill the TestCase::expectUserDeprecationMessage() and the TestCase::expectUserDeprecationMessageMatches() methods. | ||
| * | ||
| * Introduced in PHPUnit 11.0.0. | ||
| * | ||
| * Note: PHPUnit 10 is not and will not be supported for these polyfills. | ||
| * | ||
| * @link https://github.com/sebastianbergmann/phpunit/pull/5605 | ||
| */ | ||
| trait ExpectUserDeprecation { | ||
|
|
||
| /** | ||
| * Set expectation for the message when receiving a user defined deprecation notice. | ||
| * | ||
| * @param string $expectedUserDeprecationMessage The message to expect. | ||
| * | ||
| * @return void | ||
| */ | ||
| final protected function expectUserDeprecationMessage( string $expectedUserDeprecationMessage ) { | ||
| if ( \method_exists( TestCase::class, 'expectDeprecationMessage' ) ) { | ||
| // PHPUnit 8.4.0 - 9.x. | ||
| $this->expectDeprecation(); | ||
| $this->expectDeprecationMessage( $expectedUserDeprecationMessage ); | ||
| return; | ||
| } | ||
|
|
||
| // PHPUnit < 8.4.0. | ||
| $this->expectException( Deprecated::class ); | ||
| $this->expectExceptionMessage( $expectedUserDeprecationMessage ); | ||
| } | ||
|
|
||
| /** | ||
| * Set expectation for the message when receiving a user defined deprecation notice (regex based). | ||
| * | ||
| * @param string $expectedUserDeprecationMessageRegularExpression A regular expression which must match the message. | ||
| * | ||
| * @return void | ||
| */ | ||
| final protected function expectUserDeprecationMessageMatches( string $expectedUserDeprecationMessageRegularExpression ) { | ||
| if ( \method_exists( TestCase::class, 'expectDeprecationMessageMatches' ) ) { | ||
| // PHPUnit 8.4.0 - 9.x. | ||
| $this->expectDeprecation(); | ||
| $this->expectDeprecationMessageMatches( $expectedUserDeprecationMessageRegularExpression ); | ||
| return; | ||
| } | ||
|
|
||
| // PHPUnit < 8.4.0. | ||
| $this->expectException( Deprecated::class ); | ||
| $this->expectExceptionMessageRegExp( $expectedUserDeprecationMessageRegularExpression ); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| <?php | ||
|
|
||
| namespace Yoast\PHPUnitPolyfills\Polyfills; | ||
|
|
||
| /** | ||
| * Empty trait for use with PHPUnit >= 11.0.0 in which this polyfill is not needed. | ||
| */ | ||
| trait ExpectUserDeprecation {} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.