PHPUnit: allow for PHPUnit 10 + add separate configuration

The PHPunit configuration file specification has undergone changes in PHPUnit 9.3, 10.0 and 10.1.

Most notably:
* In PHPUnit 9.3, the manner of specifying the code coverage configuration has changed.
* In PHPUnit 10.0, a significant number of attributes of the `<phpunit>` element were removed or renamed.
* In PHPUnit 10.1, there is another change related to the code coverage configuration + the ability to fail builds on deprecations/warnings/notices is brought back.

While the `--migrate-configuration` command can upgrade a configuration for the changes in the format made in PHPUnit 9.3, some of the changes in the configuration format in PHPUnit 10 don't have one-on-one replacements and/or are not taken into account.

As this package is used in the CI pipeline for other packages, it is important for this package to be ready for new PHP releases _early_, so failing the test suite on deprecations/notices and warnings is appropriate.

With that in mind, I deem it more appropriate to have a dedicated PHPUnit configuration file for PHPUnit 10 to ensure the test run will behave as intended.

This commit adds this dedicated configuration file for PHPUnit 10.1+.

Includes:
* Ignoring the new file for package archives.
* Allowing for a local override file.
* Adding scripts to the `composer.json` file to run the tests using this new configuration file and make the use of the separate config make more obvious for contributors.
* Updating the GH Actions `test` workflow to trigger the tests on PHPUnit 10 with this configuration file.

Ref:
* https://github.com/sebastianbergmann/phpunit/blob/main/ChangeLog-10.0.md#1000---2023-02-03
* sebastianbergmann/phpunit 5196
* sebastianbergmann/phpunit@fb6673f

.gitattributes

@@ -3,4 +3,5 @@
 .gitattributes export-ignore
 .gitignore export-ignore
 phpunit.xml.dist export-ignore
+phpunit10.xml.dist export-ignore
 phpcs.xml.dist export-ignore

.github/workflows/test.yml

@@ -78,9 +78,18 @@ jobs:
       - name: Lint
         run: composer phplint -- --checkstyle | cs2pr
 
-      - name: Run unit tests
+      - name: Grab PHPUnit version
+        id: phpunit_version
+        run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> $GITHUB_OUTPUT
+
+      - name: "Run unit tests (PHPUnit < 10)"
+        if: ${{ ! startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}
         run: composer phpunit
 
+      - name: "Run unit tests (PHPUnit 10+)"
+        if: ${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}
+        run: composer phpunit10
+
   coverage:
     needs: test
     runs-on: ubuntu-latest

.gitignore

@@ -2,6 +2,7 @@ build
 vendor
 composer.lock
 phpunit.xml
+phpunit10.xml
 .phpunit.result.cache
 .phpcs.xml
 phpcs.xml

composer.json

@@ -22,7 +22,7 @@
         "php": ">=5.3.2"
     },
     "require-dev": {
-        "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0",
+        "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0 || ^10.1",
         "php-parallel-lint/php-parallel-lint": "^1.0",
         "php-parallel-lint/php-var-dump-check": "0.*",
         "php-parallel-lint/php-code-style": "^2.0"
@@ -51,9 +51,15 @@
         "phpunit": [
             "@php ./vendor/phpunit/phpunit/phpunit --no-coverage"
         ],
+        "phpunit10": [
+            "@php ./vendor/phpunit/phpunit/phpunit -c phpunit10.xml.dist --no-coverage"
+        ],
         "coverage": [
             "@php ./vendor/phpunit/phpunit/phpunit"
         ],
+        "coverage10": [
+            "@php ./vendor/phpunit/phpunit/phpunit -c phpunit10.xml.dist"
+        ],
         "build": [
             "@phplint",
             "@vardumpcheck",
@@ -66,8 +72,10 @@
         "vardumpcheck": "Check PHP files for forgotten variable dumps",
         "phpcs": "Check PHP code style",
         "fixcs": "Auto-fix PHP code style",
-        "phpunit": "PHP unit",
-        "coverage": "PHP unit with code coverage",
+        "phpunit": "Run the unit tests on PHPUnit 4.x - 9.x without code coverage.",
+        "phpunit10": "Run the unit tests on PHPUnit 10.x without code coverage.",
+        "coverage": "Run the unit tests on PHPUnit 4.x - 9.x with code coverage.",
+        "coverage10": "Run the unit tests on PHPUnit 10.x with code coverage.",
         "build": "Run all checks"
     }
 }

phpunit10.xml.dist

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/10.1/phpunit.xsd"
+        backupGlobals="true"
+        beStrictAboutTestsThatDoNotTestAnything="true"
+        bootstrap="./vendor/autoload.php"
+        colors="true"
+        displayDetailsOnTestsThatTriggerErrors="true"
+        displayDetailsOnTestsThatTriggerWarnings="true"
+        displayDetailsOnTestsThatTriggerNotices="true"
+        displayDetailsOnTestsThatTriggerDeprecations="true"
+        displayDetailsOnIncompleteTests="true"
+        displayDetailsOnSkippedTests="true"
+        failOnWarning="true"
+        failOnNotice="true"
+        failOnDeprecation="true"
+        requireCoverageMetadata="true"
+    >
+
+    <testsuites>
+        <testsuite name="PHP-Console-Color">
+            <directory suffix="Test.php">tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory suffix=".php">./src/</directory>
+        </include>
+    </source>
+
+    <coverage includeUncoveredFiles="true" ignoreDeprecatedCodeUnits="true">
+        <report>
+            <clover outputFile="build/logs/clover.xml"/>
+            <html outputDirectory="build/coverage/"/>
+            <text outputFile="php://stdout" showOnlySummary="true"/>
+        </report>
+    </coverage>
+
+    <php>
+        <ini name="memory_limit" value="256M"/>
+    </php>
+</phpunit>