PHPUnit config: set up to allow for recording code coverage

The `forceCoversAnnotation` attribute will prevent code coverage from being recorded for tests without a `@covers` tag.

As for recording the code coverage:
By default, a code coverage text summary will be shown and a `clover.xml` file will be generated in a `build/logs` directory.
The clover file can be used to generate code coverage reports via a service like Coveralls.

For local development, the `clover.xml` is not very human readable-friendly and the summary is a little too minimal, so an HTML report would be better.

To that end, a `coverage-local` script has been added to the `composer.json` to make it straight forward for contributors to generate the HTML report.
The HTML report will be placed in a `build/coverage-html` directory.

The `build` directory is now excluded via the `.gitignore` file.

.github/CONTRIBUTING.md

@@ -152,9 +152,8 @@ To help you with this, a number of convenience scripts are available:
 * `composer cs` will check for code style violations.
 * `composer cbf` will run the autofixers for code style violations.
 * `composer test` will run the unit tests.
-* `composer coverage` will run the unit tests with code coverage.
-    Note: you may want to use a custom `phpunit.xml` overload config file to tell PHPUnit where to place an HTML report.
-    Alternative run it like so: `composer coverage -- --coverage-html /path/to/report-dir/` to specify the location for the HTML report on the command line.
+* `composer coverage` will run the unit tests with code coverage and show a text summary.
+* `composer coverage-local` will run the unit tests with code coverage and generate an HTML coverage report, which will be placed in a `build/coverage-html` subdirectory.
 * `composer build` will build the phpcs.phar and phpcbf.phar files.
 
 N.B.: You can ignore any skipped tests as these are for external tools.

.gitignore

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

composer.json

@@ -62,6 +62,10 @@
             "Composer\\Config::disableProcessTimeout",
             "@php ./vendor/phpunit/phpunit/phpunit tests/AllTests.php -d max_execution_time=0"
         ],
+        "coverage-local": [
+            "Composer\\Config::disableProcessTimeout",
+            "@php ./vendor/phpunit/phpunit/phpunit tests/AllTests.php --coverage-html ./build/coverage-html -d max_execution_time=0"
+        ],
         "build": [
             "Composer\\Config::disableProcessTimeout",
             "@php -d phar.readonly=0 -f ./scripts/build-phar.php"
@@ -76,6 +80,7 @@
         "cbf": "Fix code style violations.",
         "test": "Run the unit tests without code coverage.",
         "coverage": "Run the unit tests with code coverage.",
+        "coverage-local": "Run the unit tests with code coverage and generate an HTML report in a 'build' directory.",
         "build": "Create PHAR files for PHPCS and PHPCBF.",
         "check-all": "Run all checks (phpcs, tests)."
     }

phpunit.xml.dist

@@ -9,10 +9,26 @@
     convertWarningsToExceptions="true"
     convertNoticesToExceptions="true"
     convertDeprecationsToExceptions="true"
+    forceCoversAnnotation="true"
     >
     <testsuites>
         <testsuite name="PHP_CodeSniffer Test Suite">
             <file>tests/AllTests.php</file>
         </testsuite>
     </testsuites>
+
+    <filter>
+        <whitelist addUncoveredFilesFromWhitelist="true" processUncoveredFilesFromWhitelist="false">
+            <directory suffix=".php">./src</directory>
+            <file>./autoload.php</file>
+            <exclude>
+                <directory suffix="UnitTest.php">./src/Standards</directory>
+            </exclude>
+        </whitelist>
+    </filter>
+
+    <logging>
+        <log type="coverage-text" target="php://stdout" showOnlySummary="true"/>
+        <log type="coverage-clover" target="build/logs/clover.xml"/>
+    </logging>
 </phpunit>