This PR can be summarized in the following changelog entry:
Preparation for compatibility with PHP 8
Relevant technical choices:
Replaces earlier PR #278
Composer: require Yoast/wp-test-utils
Adds a dev dependency to the yoast/wp-test-utils package, which will also make the PHPUnit Polyfills available.
As that package already requires and manages the installable versions for BrainMonkey and PHPUnit, remove these as explicit requirements from require-dev in favour of letting the WP Test Utils package manage the versions.
The install is done based on PHP 5.6 and includes updating the dependencies from PHPUnit itself within the constraints of maintaining compatibility with PHP 5.6.
This new package adds the following features:
Polyfills for various PHPUnit cross-version changes.
Tests: selectively switch over to the Yoast\WPTestUtils\BrainMonkey\TestCase
Not all test classes in the ACF testsuite are based on BrainMonkey and those that are generally just set up the BrainMonkey native stubs and don't add the other stubs commonly used by Yoast plugins.
With that in mind:
Selectively switch out the parent test class PHPUnit\Framework\TestCase to use Yoast\WPTestUtils\BrainMonkey\TestCase instead.
Remove redundant setUp() and tearDown() methods which are now handled in the Yoast\WPTestUtils\BrainMonkey\TestCase instead.
In the one case where the setUp() added an extra stub, rename the method to set_up() for cross-version compatibility based on the PHPUnit Polyfills.
Tests: selectively switch over to the Yoast\PHPUnitPolyfills\TestCases\TestCase
For those test classes in the ACF testsuite which are not based on BrainMonkey, we don't need the overhead of loading the BrainMonkey framework, but do want the PHPUnit cross-version compatibility.
So, the use statements referring to the PHPUnit native PHPUnit\Framework\TestCase have been replaced with use statements for the PHPUnit cross-version compatible Yoast\PHPUnitPolyfills\TestCases\TestCase.
Tests: modernize used assertions
The PHPUnit Polyfills allows for using PHPUnit 9.x assertions, even when the tests are being run on older PHPUnit versions.
This updates select assertions to the modern PHPUnit syntax, most notably, it switches out the following assertions:
assertInternalType() to assertIs[Type]().
Travis: run the tests against PHP 8/nightly
Now the tests are fully compatible with PHPUnit 9, the test suite can be run on PHP 8.
To that end, we run a composer update for just and only the test dependencies on PHP 8 to make sure that the test dependencies available are compatible with PHP 8.
And as the composer.json contains a hard-coded platform.php setting, we use ignore-platform-reqs to get round that setting.
Includes:
Adding travis_retry to composer install-like commands to get round builds stalling on the connection with Packagist, especially on older PHP versions.
Removing --prefer-dist from the composer install command as that is the default, so doesn't need to be explicitly passed.
PHPUnit config: minor tweaks
Rename the testsuite to use a more descriptive name.
Improve the code coverage configuration:
Allow for code coverage to record coverage of code in the yoast-acf-analysis.php file.
Add addUncoveredFilesFromWhitelist and processUncoveredFilesFromWhitelist directives with sensible values.
Remove the beStrictAboutCoversAnnotation attribute to not mark tests which touch code not mentioned in @covers or @uses tags as "risky".
Add the forceCoversAnnotation attribute to only record code coverage for the method under test as annotated via a @covers annotation.
Based on this configuration, the strict code coverage for this testsuite is currently 51.76%.
Test instructions
This PR can be tested by following these steps:
Verify the output of all builds for this PR, making sure that 1) the installation via Composer works without issues, 2) the tests are being run and 3) the tests pass.
To test locally, it will be simplest to:
Run composer install.
Run composer test on any PHP version below 8.0 and see the tests pass, including a more accurate assertion count (72 compared to 52 previously, due to Mockery expectations now being counted).
This confirms that the changes to the TestCase and the assertion update to use PHPUnit 9.x syntax works correctly cross-version as the PHPUnit version installed based on the composer.lock file will be PHPUnit 5.7.27.
Switch to PHP 8.
Run composer update yoast/wp-test-utils --with-dependencies --ignore-platform-reqs
Run composer test to see the tests running and passing on PHP 8 in combination with PHPUnit 9.x.
This confirms that the tests can now run cross-version on all PHPUnit versions between PHPUnit 5.7 and PHPUnit 9.x and that the tests run and pass on PHP 8.
Note: this doesn't confirm full PHP 8 compatibility yet as the test code coverage as noted above is only ~50%.
Summary
This PR can be summarized in the following changelog entry:
Relevant technical choices:
Replaces earlier PR #278
Composer: require Yoast/wp-test-utils
yoast/wp-test-utils
package, which will also make the PHPUnit Polyfills available.require-dev
in favour of letting the WP Test Utils package manage the versions.The install is done based on PHP 5.6 and includes updating the dependencies from PHPUnit itself within the constraints of maintaining compatibility with PHP 5.6.
This new package adds the following features:
Refs:
Tests: selectively switch over to the Yoast\WPTestUtils\BrainMonkey\TestCase
Not all test classes in the ACF testsuite are based on BrainMonkey and those that are generally just set up the BrainMonkey native stubs and don't add the other stubs commonly used by Yoast plugins.
With that in mind:
PHPUnit\Framework\TestCase
to useYoast\WPTestUtils\BrainMonkey\TestCase
instead.setUp()
andtearDown()
methods which are now handled in theYoast\WPTestUtils\BrainMonkey\TestCase
instead.setUp()
added an extra stub, rename the method toset_up()
for cross-version compatibility based on the PHPUnit Polyfills.Tests: selectively switch over to the Yoast\PHPUnitPolyfills\TestCases\TestCase
For those test classes in the ACF testsuite which are not based on BrainMonkey, we don't need the overhead of loading the BrainMonkey framework, but do want the PHPUnit cross-version compatibility.
So, the
use
statements referring to the PHPUnit nativePHPUnit\Framework\TestCase
have been replaced withuse
statements for the PHPUnit cross-version compatibleYoast\PHPUnitPolyfills\TestCases\TestCase
.Tests: modernize used assertions
The PHPUnit Polyfills allows for using PHPUnit 9.x assertions, even when the tests are being run on older PHPUnit versions.
This updates select assertions to the modern PHPUnit syntax, most notably, it switches out the following assertions:
assertInternalType()
toassertIs[Type]()
.Travis: run the tests against PHP 8/nightly
Now the tests are fully compatible with PHPUnit 9, the test suite can be run on PHP 8.
To that end, we run a
composer update
for just and only the test dependencies on PHP 8 to make sure that the test dependencies available are compatible with PHP 8. And as thecomposer.json
contains a hard-codedplatform.php
setting, we useignore-platform-reqs
to get round that setting.Includes:
travis_retry
tocomposer install
-like commands to get round builds stalling on the connection with Packagist, especially on older PHP versions.--prefer-dist
from thecomposer install
command as that is the default, so doesn't need to be explicitly passed.PHPUnit config: minor tweaks
yoast-acf-analysis.php
file.addUncoveredFilesFromWhitelist
andprocessUncoveredFilesFromWhitelist
directives with sensible values.beStrictAboutCoversAnnotation
attribute to not mark tests which touch code not mentioned in@covers
or@uses
tags as "risky".forceCoversAnnotation
attribute to only record code coverage for the method under test as annotated via a@covers
annotation.Based on this configuration, the strict code coverage for this testsuite is currently 51.76%.
Test instructions
This PR can be tested by following these steps:
To test locally, it will be simplest to:
composer install
.composer test
on any PHP version below 8.0 and see the tests pass, including a more accurate assertion count (72 compared to 52 previously, due to Mockery expectations now being counted). This confirms that the changes to theTestCase
and the assertion update to use PHPUnit 9.x syntax works correctly cross-version as the PHPUnit version installed based on thecomposer.lock
file will be PHPUnit 5.7.27.composer update yoast/wp-test-utils --with-dependencies --ignore-platform-reqs
composer test
to see the tests running and passing on PHP 8 in combination with PHPUnit 9.x. This confirms that the tests can now run cross-version on all PHPUnit versions between PHPUnit 5.7 and PHPUnit 9.x and that the tests run and pass on PHP 8.Note: this doesn't confirm full PHP 8 compatibility yet as the test code coverage as noted above is only ~50%.