lib/tests/deprecation_test.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 namespace core;
  18
  19 /**
  20  * Tests for \core\deprecated and \core\deprecation.
  21  *
  22  * @package    core
  23  * @category   test
  24  * @copyright  2024 Andrew Lyons <andrew@nicols.co.uk>
  25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26  * @covers \core\deprecated
  27  * @covers \core\deprecation
  28  */
  29 class deprecation_test extends \advanced_testcase {
  30     /**
  31      * @dataProvider emit_provider
  32      */
  33     public function test_emit(
  34         array $args,
  35         bool $expectdebugging,
  36         bool $expectexception,
  37     ): void {
  38         if ($expectexception) {
  39             $this->expectException(\coding_exception::class);
  40         }
  41
  42         $attribute = new deprecated(
  43             'Test description',
  44             ...$args,
  45         );
  46
  47         deprecation::emit_deprecation_notice($attribute);
  48
  49         if ($expectdebugging) {
  50             $this->assertdebuggingcalledcount(1);
  51         }
  52     }
  53
  54     public static function emit_provider(): array {
  55         return [
  56             [
  57                 [
  58                     'final' => false,
  59                     'emit' => false,
  60                 ],
  61                 false,
  62                 false,
  63             ],
  64             [
  65                 [
  66                     'final' => false,
  67                     'emit' => true,
  68                 ],
  69                 true,
  70                 false,
  71             ],
  72             [
  73                 [
  74                     'final' => true,
  75                     'emit' => false,
  76                 ],
  77                 false,
  78                 false,
  79             ],
  80             [
  81                 [
  82                     'final' => true,
  83                     'emit' => true,
  84                 ],
  85                 false,
  86                 true,
  87             ],
  88         ];
  89     }
  90
  91     /**
  92      * @dataProvider get_deprecation_string_provider
  93      */
  94     public function test_get_deprecation_string(
  95         string $descriptor,
  96         ?string $since,
  97         ?string $reason,
  98         ?string $replacement,
  99         ?string $mdl,
 100         string $expected,
 101     ): void {
 102         $attribute = new deprecated(
 103             descriptor: $descriptor,
 104             since: $since,
 105             reason: $reason,
 106             replacement: $replacement,
 107             mdl: $mdl,
 108         );
 109
 110         $this->assertEquals(
 111             $expected,
 112             deprecation::get_deprecation_string($attribute),
 113         );
 114
 115         deprecation::emit_deprecation_notice($attribute);
 116         $this->assertDebuggingCalled($expected);
 117     }
 118
 119     public static function get_deprecation_string_provider(): array {
 120         return [
 121             [
 122                 'Test description',
 123                 null,
 124                 null,
 125                 null,
 126                 null,
 127                 'Deprecation: Test description has been deprecated.',
 128             ],
 129             [
 130                 'Test description',
 131                 '4.1',
 132                 null,
 133                 null,
 134                 null,
 135                 'Deprecation: Test description has been deprecated since 4.1.',
 136             ],
 137             [
 138                 'Test description',
 139                 null,
 140                 'Test reason',
 141                 null,
 142                 null,
 143                 'Deprecation: Test description has been deprecated. Test reason.',
 144             ],
 145             [
 146                 'Test description',
 147                 null,
 148                 null,
 149                 'Test replacement',
 150                 null,
 151                 'Deprecation: Test description has been deprecated. Use Test replacement instead.',
 152             ],
 153             [
 154                 'Test description',
 155                 null,
 156                 null,
 157                 null,
 158                 'https://docs.moodle.org/311/en/Deprecated',
 159                 'Deprecation: Test description has been deprecated. See https://docs.moodle.org/311/en/Deprecated for more information.',
 160             ],
 161             [
 162                 'Test description',
 163                 '4.1',
 164                 'Test reason',
 165                 'Test replacement',
 166                 'https://docs.moodle.org/311/en/Deprecated',
 167                 'Deprecation: Test description has been deprecated since 4.1. Test reason. Use Test replacement instead. See https://docs.moodle.org/311/en/Deprecated for more information.',
 168             ],
 169         ];
 170     }
 171
 172     /**
 173      * @dataProvider from_provider
 174      */
 175     public function test_from($reference, bool $isdeprecated): void {
 176         $attribute = deprecation::from($reference);
 177         if ($isdeprecated) {
 178             $this->assertInstanceOf(deprecated::class, $attribute);
 179             $this->assertTrue(deprecation::is_deprecated($reference));
 180             $this->assertDebuggingNotCalled();
 181
 182             deprecation::emit_deprecation_if_present($reference);
 183             $this->assertDebuggingCalled(deprecation::get_deprecation_string($attribute));
 184         } else {
 185             $this->assertNull($attribute);
 186             $this->assertFalse(deprecation::is_deprecated($reference));
 187             deprecation::emit_deprecation_if_present($reference);
 188             $this->assertDebuggingNotCalled();
 189         }
 190     }
 191
 192     public function test_from_object(): void {
 193         require_once(dirname(__FILE__) . '/fixtures/deprecated_fixtures.php');
 194
 195         $this->assertNull(deprecation::from(new \core\fixtures\not_deprecated_class()));
 196         $this->assertInstanceOf(deprecated::class, deprecation::from([new \core\fixtures\deprecated_class()]));
 197     }
 198
 199     public static function from_provider(): array {
 200         require_once(dirname(__FILE__) . '/fixtures/deprecated_fixtures.php');
 201         return [
 202             // Classes.
 203             [\core\fixtures\deprecated_class::class, true],
 204             [[\core\fixtures\deprecated_class::class], true],
 205             [\core\fixtures\not_deprecated_class::class, false],
 206             [[\core\fixtures\not_deprecated_class::class], false],
 207
 208             // Class properties.
 209             [\core\fixtures\deprecated_class::class . '::deprecatedproperty', true],
 210             [[\core\fixtures\deprecated_class::class, 'deprecatedproperty'], true],
 211
 212             [\core\fixtures\deprecated_class::class . '::notdeprecatedproperty', false],
 213             [[\core\fixtures\deprecated_class::class, 'notdeprecatedproperty'], false],
 214
 215             // Class constants.
 216             [\core\fixtures\deprecated_class::class . '::DEPRECATED_CONST', true],
 217             [[\core\fixtures\deprecated_class::class, 'DEPRECATED_CONST'], true],
 218
 219             [\core\fixtures\deprecated_class::class . '::NOT_DEPRECATED_CONST', false],
 220             [[\core\fixtures\deprecated_class::class, 'NOT_DEPRECATED_CONST'], false],
 221
 222             // Class methods.
 223             [\core\fixtures\deprecated_class::class . '::deprecated_method', true],
 224             [[\core\fixtures\deprecated_class::class, 'deprecated_method'], true],
 225
 226             [\core\fixtures\deprecated_class::class . '::not_deprecated_method', false],
 227             [[\core\fixtures\deprecated_class::class, 'not_deprecated_method'], false],
 228
 229             // Non-existent class.
 230             ['non_existent_class', false],
 231             [['non_existent_class'], false],
 232
 233             // Not-deprecated class.
 234             [\core\fixtures\not_deprecated_class::class, false],
 235
 236             // Deprecated global function.
 237             ['core\fixtures\deprecated_function', true],
 238             ['core\fixtures\not_deprecated_function', false],
 239         ];
 240     }
 241 }