🔧 QA: enable unit testing for the code in this repo

This:
* Adds a PHPUnit `phpunit.xml.dist` configuration file.
* Adds a `phpunit-bootstrap.php` file to load the necessary prerequisites for the unit testing.
    The PHPCS unit test suite needs a `bootstrap` file as of PHPCS 3.1.0 which, as of then, also supports PHPUnit 6.x.
* Adds convenience scripts to the `composer.json` file to test the code of the repo.
* Adds the necessary changes to the Travis script to test against the relevant PHP / PHPCS combinations.
* And allows for individual developers to overload the `phpunit.xml.dist` file by ignoring the typical overload files.

Author: jrfnl

.gitattributes

@@ -9,6 +9,8 @@
 /.gitignore export-ignore
 /.travis.yml export-ignore
 /phpcs.xml.dist export-ignore
+/phpunit.xml.dist export-ignore
+/phpunit-bootstrap.php export-ignore
 /Debug/Tests export-ignore
 
 #

.gitignore

@@ -2,3 +2,4 @@ vendor/
 composer.lock
 .phpcs.xml
 phpcs.xml
+phpunit.xml

.travis.yml

@@ -13,19 +13,39 @@ cache:
 
 php:
   - 5.4
-  - 7.3
+  - 5.5
+  - 5.6
+  - 7.0
+  - 7.1
+  - 7.2
+
+env:
+  matrix:
+    # `master`
+    - PHPCS_VERSION="dev-master" LINT=1
+    # Lowest supported PHPCS version.
+    # In reality this is 3.0.2, but there is a bug in the unit test runner of that version.
+    - PHPCS_VERSION="3.0.2"
 
 # Define the stages used.
+# For non-PRs, only the sniff and quicktest stages are run.
+# For pull requests and merges, the full script is run (skipping quicktest).
+# Note: for pull requests, "develop" is the base branch name.
+# See: https://docs.travis-ci.com/user/conditions-v1
 stages:
   - name: sniff
+  - name: quicktest
+    if: type = push AND branch NOT IN (master, develop)
   - name: test
+    if: branch IN (master, develop)
 
 jobs:
   fast_finish: true
   include:
     #### SNIFF STAGE ####
     - stage: sniff
       php: 7.3
+      env: PHPCS_VERSION="dev-master"
       addons:
         apt:
           packages:
@@ -44,26 +64,81 @@ jobs:
         - diff -B ./PHPCSDev/ruleset.xml <(xmllint --format "./PHPCSDev/ruleset.xml")
 
 
+    #### QUICK TEST STAGE ####
+    # This is a much quicker test which only runs the unit tests and linting against the low/high
+    # supported PHP/PHPCS combinations.
+    - stage: quicktest
+      php: 7.3
+      env: PHPCS_VERSION="dev-master" LINT=1
+    - php: 7.2
+      env: PHPCS_VERSION="3.0.2"
+
+    - php: 5.4
+      env: PHPCS_VERSION="dev-master" LINT=1
+    - php: 5.4
+      env: PHPCS_VERSION="3.0.2"
+
+    #### TEST STAGE ####
+    # Additional builds to prevent issues with PHPCS versions incompatible with certain PHP versions.
+    - stage: test
+      php: 7.3
+      env: PHPCS_VERSION="dev-master" LINT=1
+    # PHPCS is only compatible with PHP 7.3 as of version 3.3.1.
+    - php: 7.3
+      env: PHPCS_VERSION="3.3.1"
+    # PHPCS is only compatible with PHP 7.4 as of version 3.5.0.
+    - php: "7.4snapshot"
+      env: PHPCS_VERSION=dev-master"
+
+  allow_failures:
+    # Allow failures for unstable builds.
+    - php: "7.4snapshot"
+
+
 before_install:
   # Speed up build time by disabling Xdebug when its not needed.
   - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
 
+  # On stable PHPCS versions, allow for PHP deprecation notices.
+  # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
+  - |
+    if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" && $PHPCS_BRANCH != "dev-master" ]]; then
+      echo 'error_reporting = E_ALL & ~E_DEPRECATED' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
+    fi
+
   - export XMLLINT_INDENT="    "
 
+  # Set up test environment using Composer.
+  - composer require --no-update --no-scripts squizlabs/php_codesniffer:${PHPCS_VERSION}
+  - |
+    if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Sniff" ]]; then
+      # The sniff stage doesn't run the unit tests, so no need for PHPUnit.
+      composer remove --dev phpunit/phpunit --no-update --no-scripts
+    elif [[ "$PHPCS_VERSION" < "3.1.0" ]]; then
+      # PHPCS < 3.1.0 is not compatible with PHPUnit 6.x.
+      composer require --dev phpunit/phpunit:"^4.0||^5.0" --no-update --no-scripts
+    elif [[ "$PHPCS_VERSION" < "3.2.3" ]]; then
+      # PHPCS < 3.2.3 is not compatible with PHPUnit 7.x.
+      composer require --dev phpunit/phpunit:"^4.0||^5.0||^6.0" --no-update --no-scripts
+    fi
+
   # --prefer-dist will allow for optimal use of the travis caching ability.
   # The Composer PHPCS plugin takes care of setting the installed_paths for PHPCS.
   - composer install --prefer-dist --no-suggest
 
 
 script:
   # Lint PHP files against parse errors.
-  - composer lint
+  - if [[ "$LINT" == "1" ]]; then composer lint; fi
 
   # Check that any sniffs available are feature complete.
   # This also acts as an integration test for the feature completeness script,
   # which is why it is run against various PHP versions and not in the "Sniff" stage.
-  - composer check-complete
+  - if [[ "$LINT" == "1" ]]; then composer check-complete; fi
 
-  # Validate the composer.json file on low/high PHP versions.
+  # Validate the composer.json file.
   # @link https://getcomposer.org/doc/03-cli.md#validate
-  - composer validate --no-check-all --strict
+  - if [[ "$LINT" == "1" ]]; then composer validate --no-check-all --strict; fi
+
+  # Run the unit tests.
+  - composer run-tests

composer.json

@@ -27,6 +27,7 @@
     },
     "require-dev" : {
         "roave/security-advisories" : "dev-master",
+        "phpunit/phpunit" : "^4.5 || ^5.0 || ^6.0 || ^7.0",
         "jakub-onderka/php-parallel-lint": "^1.0",
         "jakub-onderka/php-console-highlighter": "^0.4"
     },
@@ -43,6 +44,9 @@
         "fix-cs": [
             "@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf"
         ],
+        "run-tests": [
+            "@php ./vendor/phpunit/phpunit/phpunit --filter PHPCSStandards ./vendor/squizlabs/php_codesniffer/tests/AllTests.php"
+        ],
         "check-complete": [
             "@php ./bin/phpcs-check-feature-completeness ./Debug"
         ]

phpcs.xml.dist

@@ -40,4 +40,16 @@
     <!-- Enforce short arrays. -->
     <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
 
+
+    <!--
+    #############################################################################
+    SELECTIVE EXCLUSIONS
+    Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
+    #############################################################################
+    -->
+
+    <rule ref="PSR1.Files.SideEffects.FoundWithSymbols">
+        <exclude-pattern>/phpunit-bootstrap\.php$</exclude-pattern>
+    </rule>
+
 </ruleset>

phpunit-bootstrap.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * PHPCSDevTools, tools for PHP_CodeSniffer sniff developers.
+ *
+ * Bootstrap file for running the tests.
+ *
+ * - Load the PHPCS PHPUnit bootstrap file providing cross-version PHPUnit support.
+ *   {@link https://github.com/squizlabs/PHP_CodeSniffer/pull/1384}
+ *
+ * @package   PHPCSDevTools
+ * @copyright 2019 PHPCSDevTools Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSDevTools
+ */
+
+if (defined('PHP_CODESNIFFER_IN_TESTS') === false) {
+    define('PHP_CODESNIFFER_IN_TESTS', true);
+}
+
+$ds = DIRECTORY_SEPARATOR;
+
+/*
+ * Load the necessary PHPCS files.
+ */
+// Get the PHPCS dir from an environment variable.
+$phpcsDir          = getenv('PHPCS_DIR');
+$composerPHPCSPath = __DIR__ . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer';
+
+if ($phpcsDir === false && is_dir($composerPHPCSPath)) {
+    // PHPCS installed via Composer.
+    $phpcsDir = $composerPHPCSPath;
+} elseif ($phpcsDir !== false) {
+    /*
+     * PHPCS in a custom directory.
+     * For this to work, the `PHPCS_DIR` needs to be set in a custom `phpunit.xml` file.
+     */
+    $phpcsDir = realpath($phpcsDir);
+}
+
+// Try and load the PHPCS bootstrap which loads the autoloader and PHPUnit aliases.
+if ($phpcsDir !== false && is_dir($phpcsDir)) {
+    if (file_exists($phpcsDir . $ds . 'tests' . $ds . 'bootstrap.php')) {
+        require_once $phpcsDir . $ds . 'tests' . $ds . 'bootstrap.php'; // PHPUnit 6.x+ support as of PHPCS 3.1.0.
+    }
+} else {
+    echo 'Uh oh... can\'t find PHPCS.
+
+If you use Composer, please run `composer install`.
+Otherwise, make sure you set a `PHPCS_DIR` environment variable in your phpunit.xml file
+pointing to the PHPCS directory.
+';
+
+    die(1);
+}
+
+// Clean up.
+unset($ds, $phpcsDir, $composerPHPCSPath);

phpunit.xml.dist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.5/phpunit.xsd"
+    backupGlobals="true"
+    bootstrap="./phpunit-bootstrap.php"
+    beStrictAboutTestsThatDoNotTestAnything="false"
+    colors="true"
+    forceCoversAnnotation="true">
+
+    <testsuites>
+        <testsuite name="PHPCSDevTools">
+            <directory suffix="UnitTest.php">./Debug/Tests/</directory>
+        </testsuite>
+    </testsuites>
+
+    <php>
+        <!-- This line prevents issues with PHPCS trying to load sniff files for
+             standards which we aren't testing.
+             Ref: https://github.com/squizlabs/PHP_CodeSniffer/pull/1146 -->
+        <env name="PHPCS_IGNORE_TESTS" value="PHPCompatibility"/>
+    </php>
+</phpunit>
+