Merge pull request #619 from agh1/phpunitVersions

Testing: Update PHPUnit versions

docs/testing/phpunit.md

@@ -10,10 +10,24 @@ ensuring that the `Contact.create` API actually creates a contact.
 
 PHPUnit is a command-line tool, but the command name varies depending on how it was installed. For example:
 
-* In [buildkit](/tools/buildkit.md), this command is named `phpunit4`.
+* In [buildkit](/tools/buildkit.md), this command is named `phpunit4`, `phpunit5`, or `phpunit6`, according to the desired version of PHPUnit (see below).
 * In other environments, it might be `phpunit` or `phpunit.phar` or `phpunit.bat`.
 
-For the following examples, we'll use `phpunit4`.
+For the following examples, we'll use `phpunit5`.
+
+### PHPUnit version compatibility
+
+PHPUnit made a major breaking change in recent years: the primary base class was renamed from `PHPUnit_Framework_TestCase` to `PHPUnit\Framework\TestCase`.  Changes to `civicrm-core` in 5.14 and the `civix` test templates in 19.06.1 reflect this change.
+
+The change was implemented over the course of two versions.  PHPUnit 5 allows for both the old class name and the new one, while PHPUnit 6 only allows for the new one.  Meanwhile, PHPUnit 4 does not support PHP versions newer than 5.6.
+
+|   | PHPUnit 4 | PHPUnit 5 | PHPUnit 6 |
+| - | --------- | --------- | --------- |
+| Command | `phpunit4` | `phpunit5` | `phpunit6` |
+| Supported classes | `PHPUnit_Framework_TestCase` only | `PHPUnit_Framework_TestCase` and `PHPUnit\Framework\TestCase` | `PHPUnit\Framework\TestCase` |
+| Supported PHP versions | PHP 5.3, PHP 5.4, PHP 5.5, PHP 5.6 | PHP 5.6, PHP 7.0, PHP 7.1 | PHP 7.0, PHP 7.1, PHP 7.2 |
+| Compatible versions for `CiviUnitTestCase` | CiviCRM <= 5.14 | All | CiviCRM >= 5.15 |
+| Compatible with tests generated by civix versions | civix <=v19.06.0 | All | civix >=v19.06.1 |
 
 ## Suites
 
@@ -39,7 +53,7 @@ To run any PHPUnit test, use a command like this:
 
 ```bash
 $ cd /path/to/my/project
-$ phpunit4 ./tests/MyTest.php
+$ phpunit5 ./tests/MyTest.php
 ```
 
 Note how the command involves a few elements, such as the base-path of the project, the name of the PHPUnit binary, and the relative path of the test.
@@ -49,7 +63,7 @@ folder, `sites/all/modules/civicrm`.  To run a typical test file like `tests/php
 
 ```bash
 $ cd ~/buildkit/build/dmaster/sites/all/modules/civicrm
-$ phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php
+$ phpunit5 ./tests/phpunit/CRM/Core/RegionTest.php
 ```
 
 This command ought to work.  It's well-formed.  It *would* work in many cases -- but here it produces an error:
@@ -72,7 +86,7 @@ revised command should correct the issue:
 
 ```bash
 $ cd ~/buildkit/build/dmaster/sites/all/modules/civicrm
-$ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php
+$ env CIVICRM_UF=UnitTests phpunit5 ./tests/phpunit/CRM/Core/RegionTest.php
 ```
 
 !!! tip "Using PhpStorm for local debugging"
@@ -105,7 +119,7 @@ $ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php
 
     ```bash
     $ cd /path/to/civicrm
-    $ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/AllTests.php
+    $ env CIVICRM_UF=UnitTests phpunit5 ./tests/phpunit/CRM/AllTests.php
     ```
 
 !!! tip "Selecting tests with `--filter`, `--group`, etc"
@@ -114,7 +128,7 @@ $ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php
     execute a single test function, you can pass `--filter`, as in:
 
     ```bash
-    $ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php --filter testOverride
+    $ env CIVICRM_UF=UnitTests phpunit5 ./tests/phpunit/CRM/Core/RegionTest.php --filter testOverride
     ```
 
 !!! tip "Selecting tests with PHPUNIT_TESTS"
@@ -123,7 +137,7 @@ $ env CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/CRM/Core/RegionTest.php
     functions. For example:
 
     ```bash
-    $ env PHPUNIT_TESTS="MyFirstTest::testFoo MySecondTest" CIVICRM_UF=UnitTests phpunit4 ./tests/phpunit/EnvTests.php
+    $ env PHPUNIT_TESTS="MyFirstTest::testFoo MySecondTest" CIVICRM_UF=UnitTests phpunit5 ./tests/phpunit/EnvTests.php
     ```