[WIP] API Upgrade SapphireTest to work with phpunit 9

.travis.yml

@@ -12,29 +12,15 @@ env:
 jobs:
   fast_finish: true
   include:
-    - php: 7.1
+    - php: 7.3
       env:
         - DB=MYSQL
         - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
         - PHPCS_TEST=1
         - PHPUNIT_TEST=1
         - PHPUNIT_SUITE="framework"
         - COMPOSER_INSTALL_ARG="--prefer-lowest"
-    - php: 7.2
-      env:
-        - DB=PGSQL
-        - PDO=1
-        - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
-        - PHPUNIT_TEST=1
-        - PHPUNIT_TEST="framework"
-    - php: 7.3
-      env:
-        - DB=MYSQL
-        - PDO=1
-        - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
-        - PHPUNIT_TEST=1
-        - PHPUNIT_SUITE="framework"
-    - php: 7.3
+    - php: 7.4
       env:
         - DB=MYSQL
         - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
@@ -46,10 +32,9 @@ jobs:
         - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
         - PHPUNIT_TEST=1
         - PHPUNIT_SUITE="framework"
-    - php: nightly
+    - php: 8.0
       env:
         - DB=MYSQL
         - REQUIRE_INSTALLER="$REQUIRE_RECIPE"
         - PHPUNIT_TEST=1
         - PHPUNIT_SUITE="framework"
-        - COMPOSER_INSTALL_ARG="--ignore-platform-reqs"

composer.json

@@ -39,7 +39,7 @@
         "symfony/config": "^3.2 || ^4",
         "symfony/translation": "^2.8 || ^3 || ^4",
         "symfony/yaml": "^3.2 || ^4",
-        "php": "^7.1 || ^8",
+        "php": "^7.3 || ^8",
         "ext-ctype": "*",
         "ext-dom": "*",
         "ext-hash": "*",
@@ -52,11 +52,14 @@
         "ext-xml": "*"
     },
     "require-dev": {
-        "sminnee/phpunit": "^5.7.29",
-        "sminnee/phpunit-mock-objects": "^3.4.9",
+        "phpunit/phpunit": "^9.5",
+        "dms/phpunit-arraysubset-asserts": "^0.3.0",
         "silverstripe/versioned": "^1",
         "squizlabs/php_codesniffer": "^3.5"
     },
+    "conflict": {
+        "phpunit/phpunit": "^6 || ^7 || ^8"
+    },
     "provide": {
         "psr/container-implementation": "1.0.0"
     },

docs/en/02_Developer_Guides/06_Testing/00_Unit_Testing.md

@@ -56,7 +56,7 @@ you want to test a `Controller`, `Form` or anything that requires a web page.
 `FunctionalTest` is a subclass of `SapphireTest` so will inherit all of the behaviors. By subclassing `FunctionalTest`
 you gain the ability to load and test web pages on the site. 
 
-`SapphireTest` in turn, extends `PHPUnit_Framework_TestCase`. For more information on `PHPUnit_Framework_TestCase` see 
+`SapphireTest` in turn, extends `PHPUnit\Framework\TestCase`. For more information on `PHPUnit\Framework\TestCase` see 
 the [PHPUnit](http://www.phpunit.de) documentation. It provides a lot of fundamental concepts that we build on in this 
 documentation.
 [/info]
@@ -89,9 +89,11 @@ needs.
 ```xml
 
 <phpunit bootstrap="vendor/silverstripe/framework/tests/bootstrap.php" colors="true">
-    <testsuite name="Default">
-        <directory>app/tests</directory>
-    </testsuite>
+    <testsuites>
+        <testsuite name="Default">
+            <directory>app/tests</directory>
+        </testsuite>
+    </testsuites>
     <groups>
         <exclude>
             <group>sanitychecks</group>
@@ -115,7 +117,7 @@ class PageTest extends SapphireTest
 {
     protected $usesDatabase = true;
 
-    public function setUp()
+    protected function setUp(): void
     {
         parent::setUp();
 
@@ -152,14 +154,14 @@ use SilverStripe\Dev\SapphireTest;
 
 class PageTest extends SapphireTest
 {
-    public static function setUpBeforeClass()
+    public static function setUpBeforeClass(): void
     {
         parent::setUpBeforeClass();
 
         // ..
     }
 
-    public static function tearDownAfterClass()
+    public static function tearDownAfterClass(): void
     {
         parent::tearDownAfterClass();
 
@@ -180,7 +182,7 @@ It's important to remember that the `parent::setUp();` functions will need to be
 
 
 ```php
-public static function setUpBeforeClass()
+public static function setUpBeforeClass(): void
 {
     parent::setUpBeforeClass();
     //this will remain for the whole suite and be removed for any other tests

docs/en/02_Developer_Guides/06_Testing/How_Tos/00_Write_a_SapphireTest.md

@@ -65,9 +65,11 @@ Page:
 
 ```xml
 <phpunit bootstrap="vendor/silverstripe/framework/tests/bootstrap.php" colors="true">
-    <testsuite name="Default">
-        <directory>app/tests/</directory>
-    </testsuite>
+    <testsuites>
+        <testsuite name="Default">
+            <directory>app/tests/</directory>
+        </testsuite>
+    </testsuites>
     <filter>
         <whitelist addUncoveredFilesFromWhitelist="true">
             <directory suffix=".php">app/src</directory>

phpunit.xml.dist

@@ -1,18 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 Standard module phpunit configuration.
-Requires PHPUnit ^5.7
+Requires PHPUnit ^9
 -->
 <phpunit bootstrap="tests/bootstrap.php" colors="true">
-	<testsuite name="Default">
-		<directory>tests/php</directory>
-    </testsuite>
-    <testsuite name="framework">
-        <directory>tests/php</directory>
-    </testsuite>
-    <testsuite name="cms">
-        <directory>vendor/silverstripe/cms/tests</directory>
-    </testsuite>
+    <testsuites>
+        <testsuite name="Default">
+            <directory>tests/php</directory>
+        </testsuite>
+        <testsuite name="framework">
+            <directory>tests/php</directory>
+        </testsuite>
+        <testsuite name="cms">
+            <directory>vendor/silverstripe/cms/tests</directory>
+        </testsuite>
+    </testsuites>
     <filter>
         <whitelist addUncoveredFilesFromWhitelist="true">
             <directory suffix=".php">.</directory>

src/Dev/Constraint/SSListContains.php

@@ -4,11 +4,165 @@
 
 use PHPUnit_Framework_Constraint;
 use PHPUnit_Framework_ExpectationFailedException;
+use PHPUnit\Framework\Constraint\Constraint;
+use PHPUnit\Framework\ExpectationFailedException;
 use SilverStripe\Dev\SSListExporter;
 use SilverStripe\Dev\TestOnly;
 use SilverStripe\ORM\SS_List;
 use SilverStripe\View\ViewableData;
 
+/* -------------------------------------------------
+ *
+ * This version of SSListContains is for phpunit 9
+ * The phpunit 5 version is lower down in this file
+ * phpunit 6, 7 and 8 are not supported
+ *
+ * @see SilverStripe\Dev\SapphireTest
+ *
+ * -------------------------------------------------
+ */
+
+if (class_exists(Constraint::class)) {
+
+    /**
+     * Constraint for checking if a SS_List contains items matching the given
+     * key-value pairs.
+     */
+    // Ignore multiple classes in same file
+    // @codingStandardsIgnoreStart
+    class SSListContains extends Constraint implements TestOnly
+    {
+        // @codingStandardsIgnoreEnd
+        /**
+         * @var array
+         */
+        protected $matches = [];
+
+        /**
+         * Check if the list has left over items that don't match
+         *
+         * @var bool
+         */
+        protected $hasLeftoverItems = false;
+
+        public function __construct(array $matches)
+        {
+            $this->exporter = new SSListExporter();
+
+            $this->matches = $matches;
+        }
+
+        /**
+         * Evaluates the constraint for parameter $other
+         *
+         * If $returnResult is set to false (the default), an exception is thrown
+         * in case of a failure. null is returned otherwise.
+         *
+         * If $returnResult is true, the result of the evaluation is returned as
+         * a boolean value instead: true in case of success, false in case of a
+         * failure.
+         *
+         * @param SS_List $other Value or object to evaluate.
+         * @param string $description Additional information about the test
+         * @param bool $returnResult Whether to return a result or throw an exception
+         *
+         * @return null|bool
+         *
+         * @throws PHPUnit_Framework_ExpectationFailedException
+         */
+        public function evaluate($other, $description = '', $returnResult = false): ?bool
+        {
+            $success = true;
+
+            foreach ($other as $item) {
+                $this->checkIfItemEvaluatesRemainingMatches($item);
+            }
+
+            //we have remaining matches?
+            if (count($this->matches) !== 0) {
+                $success = false;
+                $this->hasLeftoverItems = true;
+            }
+
+            if ($returnResult) {
+                return $success;
+            }
+
+            if (!$success) {
+                $this->fail($other, $description);
+            }
+
+            return null;
+        }
+
+        /**
+         * @param ViewableData $item
+         * @return bool
+         */
+        protected function checkIfItemEvaluatesRemainingMatches(ViewableData $item): bool
+        {
+            $success = false;
+            foreach ($this->matches as $key => $match) {
+                $constraint = new ViewableDataContains($match);
+
+                if ($constraint->evaluate($item, '', true)) {
+                    $success = true;
+                    unset($this->matches[$key]);
+                    break;
+                }
+            }
+
+            return $success;
+        }
+
+        /**
+         * Returns a string representation of the object.
+         *
+         * @return string
+         */
+        public function toString(): string
+        {
+            $matchToString = function ($key, $value) {
+                return ' "' . $key . '" is "' . $value . '"';
+            };
+
+            $matchesToString = function ($matches) use ($matchToString) {
+                $matchesAsString = implode(' and ', array_map(
+                    $matchToString,
+                    array_keys($matches),
+                    array_values($matches)
+                ));
+
+                return '(' . $matchesAsString . ')';
+            };
+
+            $allMatchesAsString = implode(
+                "\n or ",
+                array_map($matchesToString, $this->matches)
+            );
+
+
+            return $this->getStubForToString() . $allMatchesAsString;
+        }
+
+        /**
+         * @return string
+         */
+        protected function getStubForToString(): string
+        {
+            return ' contains an item matching ';
+        }
+    }
+}
+
+/* -------------------------------------------------
+ *
+ * This version of FunctionalTest is for phpunit 5
+ * The phpunit 9 verison is at the top of this file
+ *
+ * -------------------------------------------------
+ */
+
 if (!class_exists(PHPUnit_Framework_Constraint::class)) {
     return;
 }
@@ -17,8 +171,11 @@
  * Constraint for checking if a SS_List contains items matching the given
  * key-value pairs.
  */
+// Ignore multiple classes in same file
+// @codingStandardsIgnoreStart
 class SSListContains extends PHPUnit_Framework_Constraint implements TestOnly
 {
+    // @codingStandardsIgnoreEnd
     /**
      * @var array
      */
@@ -33,7 +190,6 @@ class SSListContains extends PHPUnit_Framework_Constraint implements TestOnly
 
     public function __construct($matches)
     {
-        parent::__construct();
         $this->exporter = new SSListExporter();
 
         $this->matches = $matches;
@@ -55,7 +211,7 @@ public function __construct($matches)
      *
      * @return null|bool
      *
-     * @throws PHPUnit_Framework_ExpectationFailedException
+     * @throws ExpectationFailedException
      */
     public function evaluate($other, $description = '', $returnResult = false)
     {
@@ -132,6 +288,9 @@ public function toString()
         return $this->getStubForToString() . $allMatchesAsString;
     }
 
+    /**
+     * @return string
+     */
     protected function getStubForToString()
     {
         return ' contains an item matching ';