GH Actions: warm PHPUnit cache on PHPUnit 9.3+

As of PHPUnit 9.3, PHPUnit started using PHP-Parser as a basis to calculate code coverage. PHP Parser also polyfills tokens and that can interfere with the sniffs, but only in code coverage runs.

In PHPUnit 9.3.4 a new feature was added to warm the code cache ahead of running tests recording code coverage. Using that feature should prevent the token interference.

So far, I've not seen problems with this for this codebase, but better safe than sorry, so I'm going to enable cache warming now anyway.

Notes regarding cache-warming:
* The `--coverage-cache` and `--warm-coverage-cache` options are available since PHPUnit 9.3.4 and if these are used on older PHPUnit versions, PHPUnit will error out with an "unrecognized CLI argument" error.
* In other words: these options can only be used with PHPUnit 9.3+, which is why the PHPUnit version is checked and remembered and subsequently used in the conditions.
* Also: running PHPUnit with the `--warm-coverage-cache` option _does not run the tests_. It literally only warms the cache, which is why this is implemented as a separate step in the workflow.
* The cache directory can be configured in the `phpunit.xml[.dist]` file, but only when using the PHPUnit 9.3+ `coverage` XML tag.
    As the PHPUnit config used needs to stay cross-version compatible with older PHPUnit versions, the CLI option is used for now.

Refs:
* sebastianbergmann/php-code-coverage#798 (comment)
* sebastianbergmann/phpunit@9.3.3...9.3.4

Also note that PHP-Parser 5.0 was released a couple of days ago and when used for code coverage runs on PHP 8.0 (as used for the 4.0 branch), this causes problems.

When I merge this commit up to 4.0, I will adjust the GH Actions script for the 4.0 branch to use PHP 8.1 instead of PHP 8.0 to avoid this issue.

The issue has been reported upstream: sebastianbergmann/php-code-coverage#1025

.github/workflows/test.yml

@@ -234,12 +234,33 @@ jobs:
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")
 
+      - name: Grab PHPUnit version
+        id: phpunit_version
+        # yamllint disable-line rule:line-length
+        run: echo "VERSION=$(vendor/bin/phpunit --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')" >> $GITHUB_OUTPUT
+
+      - name: "DEBUG: Show grabbed version"
+        run: echo ${{ steps.phpunit_version.outputs.VERSION }}
+
       - name: 'PHPCS: set the path to PHP'
         run: php bin/phpcs --config-set php_path php
 
-      - name: 'PHPUnit: run the tests with code coverage'
+      # PHPUnit 9.3 started using PHP-Parser for code coverage, which can cause issues due to Parser
+      # also polyfilling PHP tokens.
+      # As of PHPUnit 9.3.4, a cache warming option is available.
+      # Using that option prevents issues with PHP-Parser backfilling PHP tokens during our test runs.
+      - name: "Warm the PHPUnit cache (PHPUnit 9.3+)"
+        if: ${{ steps.phpunit_version.outputs.VERSION >= '9.3' }}
+        run: vendor/bin/phpunit --coverage-cache ./build/phpunit-cache --warm-coverage-cache
+
+      - name: "Run the unit tests with code coverage (PHPUnit < 9.3)"
+        if: ${{ steps.phpunit_version.outputs.VERSION < '9.3' }}
         run: vendor/bin/phpunit tests/AllTests.php
 
+      - name: "Run the unit tests with code coverage (PHPUnit 9.3+)"
+        if: ${{ steps.phpunit_version.outputs.VERSION >= '9.3' }}
+        run: vendor/bin/phpunit tests/AllTests.php --coverage-cache ./build/phpunit-cache
+
       - name: Upload coverage results to Coveralls
         if: ${{ success() }}
         uses: coverallsapp/github-action@v2

composer.json

@@ -36,7 +36,7 @@
         "ext-xmlwriter": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^4.0 || ^5.0 || ^6.0 || ^7.0 || ^8.0 || ^9.0"
+        "phpunit/phpunit": "^4.0 || ^5.0 || ^6.0 || ^7.0 || ^8.0 || ^9.3.4"
     },
     "bin": [
         "bin/phpcbf",