You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
PHPUnit 11 | ExpectUserDeprecationtrait: polyfill the TestCase::expectUserDeprecation*() 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
This functionality resembles the functionality previously offered by the `TestCase::expectDeprecationMessage()` and `TestCase::expectDeprecationMessageMatches()` methods, which were removed in PHPUnit 10.0.0.
455
+
456
+
The polyfill use the old methods under the hood for PHPUnit <= 9, however, there are some pertinent differences in behaviour between the old and the new methods, which users of the polyfill should be aware of.
457
+
458
+
| PHPUnit <= 9.x | PHPUnit >= 11.0 |
459
+
| -------------- | --------------- |
460
+
| Only one deprecation can be expected per test | Multiple deprecations can be expected per test |
461
+
| The test stops running as soon as the deprecation message has been seen | The test will be executed completely, independently of the deprecation notice |
462
+
| The message passed to `expectUserDeprecationMessage()` will be compared as a substring | The message passed to `expectUserDeprecationMessage()` must be an exact match |
463
+
| Can expect both PHP native and user-land deprecation notices | Can only expect user-land deprecation notices, i.e. `E_USER_DEPRECATED`, not `E_DEPRECATED`|
464
+
465
+
Please keep these differences in mind when writing tests using the `expectUserDeprecationMessage*()` methods.
466
+
467
+
Note: on PHPUnit 9.5.x, when using the `expectUserDeprecationMessage*()` expectations, a "_Expecting E_DEPRECATED and E_USER_DEPRECATED is deprecated and will no longer be possible in PHPUnit 10._" deprecation will be shown in the test output.
468
+
As long at the actual test uses the `expectUserDeprecationMessage*()` expectations, this depreation message can be safely ignored.
469
+
470
+
> :information_source: Important: when using the `expectUserDeprecationMessage*()` expectation(s) in a test, the test should be annotated with a [`#[IgnoreDeprecations]`][ignoredeprecations-attribute] attribute.
0 commit comments