From 3348557daf1eb75bd0ab9c5175d24538d0f49711 Mon Sep 17 00:00:00 2001
From: Andrew Hunt <andrew@aghstrategies.com>
Date: Mon, 10 Jun 2019 15:01:19 -0400
Subject: [PATCH] Testing: discuss PHPUnit versions
---
docs/testing/phpunit.md | 30 ++++++++++++++++++++++--------
1 file changed, 22 insertions(+), 8 deletions(-)
diff --git a/docs/testing/phpunit.md b/docs/testing/phpunit.md
index 7eef1ae5..2bcfcb1a 100644
--- a/docs/testing/phpunit.md
+++ b/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
```
--
GitLab