MDL-67673 phpunit: deprecate old phpunit/dbunit stuff
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Wed, 7 Oct 2020 10:02:19 +0000 (12:02 +0200)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Wed, 21 Oct 2020 10:46:00 +0000 (12:46 +0200)
Apply the standard deprecation procedure to the old APIs, to
be removed in Moodle 4.2 (MDL-69882). Existing unit tests
cover the deprecation debugging.

Originally MDL-64600

lib/phpunit/classes/advanced_testcase.php
lib/phpunit/classes/arraydataset.php [deleted file]
lib/phpunit/tests/advanced_test.php
lib/upgrade.txt

index 31b7a61..15de839 100644 (file)
@@ -146,31 +146,26 @@ abstract class advanced_testcase extends base_testcase {
         }
     }
 
-    /**
-     * Creates a new FlatXmlDataSet with the given $xmlFile. (absolute path.)
-     *
-     * @param string $xmlFile
-     * @return PHPUnit\DbUnit\DataSet\FlatXmlDataSet
-     */
-    protected function createFlatXMLDataSet($xmlFile) {
-        // TODO: MDL-67673 - removed
-        return new PHPUnit\DbUnit\DataSet\FlatXmlDataSet($xmlFile);
-    }
-
     /**
      * Creates a new XMLDataSet with the given $xmlFile. (absolute path.)
      *
+     * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info.
+     * @todo This will be removed for Moodle 4.2 as part of MDL-69882.
+     *
      * @param string $xmlFile
-     * @return PHPUnit\DbUnit\DataSet\XmlDataSet
+     * @return phpunit_dataset
      */
     protected function createXMLDataSet($xmlFile) {
-        // TODO: MDL-67673 - deprecate this (debugging...)
+        debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_files() instead.', DEBUG_DEVELOPER);
         return $this->dataset_from_files([$xmlFile]);
     }
 
     /**
      * Creates a new CsvDataSet from the given array of csv files. (absolute paths.)
      *
+     * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info.
+     * @todo This will be removed for Moodle 4.2 as part of MDL-69882.
+     *
      * @param array $files array tablename=>cvsfile
      * @param string $delimiter unused
      * @param string $enclosure unused
@@ -178,31 +173,37 @@ abstract class advanced_testcase extends base_testcase {
      * @return phpunit_dataset
      */
     protected function createCsvDataSet($files, $delimiter = ',', $enclosure = '"', $escape = '"') {
-        // TODO: MDL-67673 - deprecate this (debugging...)
+        debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_files() instead.', DEBUG_DEVELOPER);
         return $this->dataset_from_files($files);
     }
 
     /**
      * Creates new ArrayDataSet from given array
      *
+     * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info.
+     * @todo This will be removed for Moodle 4.2 as part of MDL-69882.
+     *
      * @param array $data array of tables, first row in each table is columns
-     * @return phpunit_ArrayDataSet
+     * @return phpunit_dataset
      */
     protected function createArrayDataSet(array $data) {
-        // TODO: MDL-67673 - deprecate this (debugging...)
+        debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_array() instead.', DEBUG_DEVELOPER);
         return $this->dataset_from_array($data);
     }
 
     /**
      * Load date into moodle database tables from standard PHPUnit data set.
      *
+     * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info.
+     * @todo This will be removed for Moodle 4.2 as part of MDL-69882.
+     *
      * Note: it is usually better to use data generators
      *
      * @param phpunit_dataset $dataset
      * @return void
      */
     protected function loadDataSet(phpunit_dataset $dataset) {
-        // TODO: MDL-67673 - deprecate this (debugging...)
+        debugging(__FUNCTION__ . '() is deprecated. Please use dataset->to_database() instead.', DEBUG_DEVELOPER);
         $dataset->to_database();
     }
 
@@ -218,6 +219,8 @@ abstract class advanced_testcase extends base_testcase {
      *       'course' => '/path/to/courses.csv',
      *   ];
      *
+     * @since Moodle 3.10
+     *
      * @param array $files full paths to CSV or XML files to load.
      * @return phpunit_dataset
      */
@@ -231,9 +234,12 @@ abstract class advanced_testcase extends base_testcase {
     /**
      * Creates a new dataset from string (CSV or XML).
      *
+     * @since Moodle 3.10
+     *
      * @param string $content contents (CSV or XML) to load.
      * @param string $type format of the content to be loaded (csv or xml).
      * @param string $table name of the table which the file belongs to (only for CSV files).
+     * @return phpunit_dataset
      */
     protected function dataset_from_string(string $content, string $type, ?string $table = null) {
         $dataset = new phpunit_dataset();
@@ -244,6 +250,8 @@ abstract class advanced_testcase extends base_testcase {
     /**
      * Creates a new dataset from PHP array.
      *
+     * @since Moodle 3.10
+     *
      * @param array $data array of tables, see {@see phpunit_dataset::from_array()} for supported formats.
      * @return phpunit_dataset
      */
diff --git a/lib/phpunit/classes/arraydataset.php b/lib/phpunit/classes/arraydataset.php
deleted file mode 100644 (file)
index f91086f..0000000
+++ /dev/null
@@ -1,85 +0,0 @@
-<?php
-// This file is part of Moodle - http://moodle.org/
-//
-// Moodle is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// Moodle is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
-
-/**
- * Array based data iterator.
- *
- * @package    core
- * @category   phpunit
- * @copyright  2012 Petr Skoda {@link http://skodak.org}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
-
-
-/**
- * Based on array iterator code from PHPUnit documentation by Sebastian Bergmann
- * with new constructor parameter for different array types.
- *
- * @package    core
- * @category   phpunit
- * @copyright  2012 Petr Skoda {@link http://skodak.org}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
-class phpunit_ArrayDataSet extends PHPUnit\DbUnit\DataSet\AbstractDataSet {
-    /**
-     * @var array
-     */
-    protected $tables = array();
-
-    /**
-     * @param array $data
-     */
-    public function __construct(array $data) {
-        foreach ($data AS $tableName => $rows) {
-            $firstrow = reset($rows);
-
-            if (array_key_exists(0, $firstrow)) {
-                // columns in first row
-                $columnsInFirstRow = true;
-                $columns = $firstrow;
-                $key = key($rows);
-                unset($rows[$key]);
-            } else {
-                // column name is in each row as key
-                $columnsInFirstRow = false;
-                $columns = array_keys($firstrow);
-            }
-
-            $metaData = new PHPUnit\DbUnit\DataSet\DefaultTableMetadata($tableName, $columns);
-            $table = new PHPUnit\DbUnit\DataSet\DefaultTable($metaData);
-
-            foreach ($rows AS $row) {
-                if ($columnsInFirstRow) {
-                    $row = array_combine($columns, $row);
-                }
-                $table->addRow($row);
-            }
-            $this->tables[$tableName] = $table;
-        }
-    }
-
-    protected function createIterator($reverse = FALSE) {
-        return new PHPUnit\DbUnit\DataSet\DefaultTableIterator($this->tables, $reverse);
-    }
-
-    public function getTable($tableName) {
-        if (!isset($this->tables[$tableName])) {
-            throw new InvalidArgumentException("$tableName is not a table in the current database.");
-        }
-
-        return $this->tables[$tableName];
-    }
-}
index 9a60a82..8a2e142 100644 (file)
@@ -326,7 +326,9 @@ class core_phpunit_advanced_testcase extends advanced_testcase {
         $this->assertFalse($DB->record_exists('user', array('id' => 5)));
         $this->assertFalse($DB->record_exists('user', array('id' => 7)));
         $dataset = $this->createXMLDataSet(__DIR__.'/fixtures/sample_dataset.xml');
+        $this->assertDebuggingCalled('createXMLDataSet() is deprecated. Please use dataset_from_files() instead.');
         $this->loadDataSet($dataset);
+        $this->assertDebuggingCalled('loadDataSet() is deprecated. Please use dataset->to_database() instead.');
         $this->assertTrue($DB->record_exists('user', array('id' => 5)));
         $this->assertTrue($DB->record_exists('user', array('id' => 7)));
         $user5 = $DB->get_record('user', array('id' => 5));
@@ -344,7 +346,9 @@ class core_phpunit_advanced_testcase extends advanced_testcase {
         $this->assertFalse($DB->record_exists('user', array('id' => 8)));
         $this->assertFalse($DB->record_exists('user', array('id' => 9)));
         $dataset = $this->createCsvDataSet(array('user' => __DIR__.'/fixtures/sample_dataset.csv'));
+        $this->assertDebuggingCalled('createCsvDataSet() is deprecated. Please use dataset_from_files() instead.');
         $this->loadDataSet($dataset);
+        $this->assertDebuggingCalled('loadDataSet() is deprecated. Please use dataset->to_database() instead.');
         $this->assertEquals(5, $DB->get_field('user', 'id', array('username' => 'bozka.novakova')));
         $this->assertEquals(7, $DB->get_field('user', 'id', array('username' => 'pepa.novak')));
 
@@ -366,7 +370,9 @@ class core_phpunit_advanced_testcase extends advanced_testcase {
         $this->assertFalse($DB->record_exists('user', array('email' => 'top@example.com')));
         $this->assertFalse($DB->record_exists('user', array('email' => 'low@example.com')));
         $dataset = $this->createArrayDataSet($data);
+        $this->assertDebuggingCalled('createArrayDataSet() is deprecated. Please use dataset_from_array() instead.');
         $this->loadDataSet($dataset);
+        $this->assertDebuggingCalled('loadDataSet() is deprecated. Please use dataset->to_database() instead.');
         $this->assertTrue($DB->record_exists('user', array('email' => 'top@example.com')));
         $this->assertTrue($DB->record_exists('user', array('email' => 'low@example.com')));
 
@@ -377,7 +383,9 @@ class core_phpunit_advanced_testcase extends advanced_testcase {
             ),
         );
         $dataset = $this->createArrayDataSet($data);
+        $this->assertDebuggingCalled('createArrayDataSet() is deprecated. Please use dataset_from_array() instead.');
         $this->loadDataSet($dataset);
+        $this->assertDebuggingCalled('loadDataSet() is deprecated. Please use dataset->to_database() instead.');
         $this->assertTrue($DB->record_exists('user', array('username' => 'noidea')));
         $this->assertTrue($DB->record_exists('user', array('username' => 'onemore')));
     }
index 40aa910..e4dbf87 100644 (file)
@@ -2,6 +2,18 @@ This files describes API changes in core libraries and APIs,
 information provided here is intended especially for developers.
 
 === 3.10 ===
+* PHPUnit has been upgraded to 8.5. That comes with a few changes:
+  - phpunit/dbunit is not available any more and it has been replaced by a lightweight phpunit_dataset class, able to
+    load XML/CSV and PHP arrays, send the to database and return rows to calling code (in tests). That implies the
+    follwoing changes in the advanced_testcase class:
+      - createFlatXMLDataSet() has been removed. No uses in core, uses can switch to createXMLDataSet() (read below).
+      - createXMLDataSet() has been deprecated. Use dataset_from_files() instead.
+      - createCsvDataSet() has been deprecated. Use dataset_from_files() instead.
+      - createArrayDataSet() has been deprecated. This method was using the phpunit_ArrayDataSet class
+        that has been also removed from core. Use dataset_from_array() instead.
+      - loadDataSet() has been deprecated. Use phpunit_dataset->to_database() instead.
+      - All the previous uses of phpunit/dbunit methods like Dataset:getRows(), Dataset::getRowCount()
+        must be replaced by the new phpunit_dataset->get_rows() method.
 * Retains the source course id when a course is copied from another course on the same site.
 * Added function setScrollable in core/modal. This function can be used to set the modal's body to be scrollable or not
   when the modal's height exceeds the browser's height. This is also supported in core/modal_factory through the