[Summary view]

Differences Between: [Versions 402 and 403]

   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_external;
  18  
  19  /**
  20   * Unit tests for core_external\external_api.
  21   *
  22   * @package     core_external
  23   * @category    test
  24   * @copyright   2022 Andrew Lyons <andrew@nicols.co.uk>
  25   * @license     http://www.gnu.org/copyleft/gpl.html GNU Public License
  26   * @covers      \core_external\external_api
  27   */
  28  class external_api_test extends \advanced_testcase {
  29      /**
  30       * Test the validate_parameters method.
  31       *
  32       * @covers \core_external\external_api::validate_parameters
  33       */
  34      public function test_validate_params(): void {
  35          $params = ['text' => 'aaa', 'someid' => '6'];
  36          $description = new external_function_parameters([
  37              'someid' => new external_value(PARAM_INT, 'Some int value'),
  38              'text'   => new external_value(PARAM_ALPHA, 'Some text value'),
  39          ]);
  40          $result = external_api::validate_parameters($description, $params);
  41          $this->assertCount(2, $result);
  42          reset($result);
  43          $this->assertSame('someid', key($result));
  44          $this->assertSame(6, $result['someid']);
  45          $this->assertSame('aaa', $result['text']);
  46  
  47          $params = [
  48              'someids' => ['1', 2, 'a' => '3'],
  49              'scalar' => 666,
  50          ];
  51          $description = new external_function_parameters([
  52              'someids' => new external_multiple_structure(new external_value(PARAM_INT, 'Some ID')),
  53              'scalar'  => new external_value(PARAM_ALPHANUM, 'Some text value'),
  54          ]);
  55          $result = external_api::validate_parameters($description, $params);
  56          $this->assertCount(2, $result);
  57          reset($result);
  58          $this->assertSame('someids', key($result));
  59          $this->assertEquals([0 => 1, 1 => 2, 2 => 3], $result['someids']);
  60          $this->assertSame('666', $result['scalar']);
  61  
  62          $params = ['text' => 'aaa'];
  63          $description = new external_function_parameters([
  64              'someid' => new external_value(PARAM_INT, 'Some int value', VALUE_DEFAULT),
  65              'text'   => new external_value(PARAM_ALPHA, 'Some text value'),
  66          ]);
  67          $result = external_api::validate_parameters($description, $params);
  68          $this->assertCount(2, $result);
  69          reset($result);
  70          $this->assertSame('someid', key($result));
  71          $this->assertNull($result['someid']);
  72          $this->assertSame('aaa', $result['text']);
  73  
  74          $params = ['text' => 'aaa'];
  75          $description = new external_function_parameters([
  76              'someid' => new external_value(PARAM_INT, 'Some int value', VALUE_DEFAULT, 6),
  77              'text'   => new external_value(PARAM_ALPHA, 'Some text value'),
  78          ]);
  79          $result = external_api::validate_parameters($description, $params);
  80          $this->assertCount(2, $result);
  81          reset($result);
  82          $this->assertSame('someid', key($result));
  83          $this->assertSame(6, $result['someid']);
  84          $this->assertSame('aaa', $result['text']);
  85      }
  86  
  87      /**
  88       * Test for clean_returnvalue() for testing that returns the PHP type.
  89       *
  90       * @covers \core_external\external_api::clean_returnvalue
  91       */
  92      public function test_clean_returnvalue_return_php_type(): void {
  93          $returndesc = new external_single_structure([
  94              'value' => new external_value(PARAM_RAW, 'Some text', VALUE_OPTIONAL, null, NULL_NOT_ALLOWED),
  95          ]);
  96  
  97          // Check return type on exception because the external values does not allow NULL values.
  98          $testdata = ['value' => null];
  99          try {
 100              $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 101          } catch (\moodle_exception $e) {
 102              $this->assertInstanceOf(\invalid_response_exception::class, $e);
 103              $this->assertStringContainsString('of PHP type "NULL"', $e->debuginfo);
 104          }
 105      }
 106  
 107      /**
 108       * Test for clean_returnvalue().
 109       *
 110       * @covers \core_external\external_api::clean_returnvalue
 111       */
 112      public function test_clean_returnvalue(): void {
 113          // Build some return value decription.
 114          $returndesc = new external_multiple_structure(
 115              new external_single_structure(
 116                  [
 117                      'object' => new external_single_structure(
 118                                  ['value1' => new external_value(PARAM_INT, 'this is a int')]),
 119                      'value2' => new external_value(PARAM_TEXT, 'some text', VALUE_OPTIONAL),
 120                  ]
 121              ));
 122  
 123          // Clean an object (it should be cast into an array).
 124          $object = new \stdClass();
 125          $object->value1 = 1;
 126          $singlestructure['object'] = $object;
 127          $singlestructure['value2'] = 'Some text';
 128          $testdata = [$singlestructure];
 129          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 130          $cleanedsinglestructure = array_pop($cleanedvalue);
 131          $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
 132          $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
 133  
 134          // Missing VALUE_OPTIONAL.
 135          $object = new \stdClass();
 136          $object->value1 = 1;
 137          $singlestructure = new \stdClass();
 138          $singlestructure->object = $object;
 139          $testdata = [$singlestructure];
 140          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 141          $cleanedsinglestructure = array_pop($cleanedvalue);
 142          $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
 143          $this->assertArrayNotHasKey('value2', $cleanedsinglestructure);
 144  
 145          // Unknown attribute (the value should be ignored).
 146          $object = [];
 147          $object['value1'] = 1;
 148          $singlestructure = [];
 149          $singlestructure['object'] = $object;
 150          $singlestructure['value2'] = 'Some text';
 151          $singlestructure['unknownvalue'] = 'Some text to ignore';
 152          $testdata = [$singlestructure];
 153          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 154          $cleanedsinglestructure = array_pop($cleanedvalue);
 155          $this->assertSame($object['value1'], $cleanedsinglestructure['object']['value1']);
 156          $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
 157          $this->assertArrayNotHasKey('unknownvalue', $cleanedsinglestructure);
 158  
 159          // Missing required value (an exception is thrown).
 160          $object = [];
 161          $singlestructure = [];
 162          $singlestructure['object'] = $object;
 163          $singlestructure['value2'] = 'Some text';
 164          $testdata = [$singlestructure];
 165          $this->expectException('invalid_response_exception');
 166          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 167      }
 168  
 169      /**
 170       * Test \core_external\external_api::get_context_from_params().
 171       *
 172       * @covers \core_external\external_api::get_context_from_params
 173       */
 174      public function test_get_context_from_params(): void {
 175          $this->resetAfterTest(true);
 176          $course = $this->getDataGenerator()->create_course();
 177          $realcontext = \context_course::instance($course->id);
 178  
 179          // Use context id.
 180          $fetchedcontext = $this->get_context_from_params(["contextid" => $realcontext->id]);
 181          $this->assertEquals($realcontext, $fetchedcontext);
 182  
 183          // Use context level and instance id.
 184          $fetchedcontext = $this->get_context_from_params(["contextlevel" => "course", "instanceid" => $course->id]);
 185          $this->assertEquals($realcontext, $fetchedcontext);
 186  
 187          // Use context level numbers instead of legacy short level names.
 188          $fetchedcontext = $this->get_context_from_params(
 189              ["contextlevel" => \core\context\course::LEVEL, "instanceid" => $course->id]);
 190          $this->assertEquals($realcontext, $fetchedcontext);
 191  
 192          // Passing empty values.
 193          try {
 194              $fetchedcontext = $this->get_context_from_params(["contextid" => 0]);
 195              $this->fail('Exception expected from get_context_wrapper()');
 196          } catch (\moodle_exception $e) {
 197              $this->assertInstanceOf(\invalid_parameter_exception::class, $e);
 198          }
 199  
 200          try {
 201              $fetchedcontext = $this->get_context_from_params(["instanceid" => 0]);
 202              $this->fail('Exception expected from get_context_wrapper()');
 203          } catch (\moodle_exception $e) {
 204              $this->assertInstanceOf(\invalid_parameter_exception::class, $e);
 205          }
 206  
 207          try {
 208              $fetchedcontext = $this->get_context_from_params(["contextid" => null]);
 209              $this->fail('Exception expected from get_context_wrapper()');
 210          } catch (\moodle_exception $e) {
 211              $this->assertInstanceOf(\invalid_parameter_exception::class, $e);
 212          }
 213  
 214          // Tests for context with instanceid equal to 0 (System context).
 215          $realcontext = \context_system::instance();
 216          $fetchedcontext = $this->get_context_from_params(["contextlevel" => "system", "instanceid" => 0]);
 217          $this->assertEquals($realcontext, $fetchedcontext);
 218  
 219          // Passing wrong level name.
 220          try {
 221              $fetchedcontext = $this->get_context_from_params(["contextlevel" => "random", "instanceid" => $course->id]);
 222              $this->fail('exception expected when level name is invalid');
 223          } catch (\moodle_exception $e) {
 224              $this->assertInstanceOf('invalid_parameter_exception', $e);
 225              $this->assertSame('Invalid parameter value detected (Invalid context level = random)', $e->getMessage());
 226          }
 227  
 228          // Passing wrong level number.
 229          try {
 230              $fetchedcontext = $this->get_context_from_params(["contextlevel" => -10, "instanceid" => $course->id]);
 231              $this->fail('exception expected when level name is invalid');
 232          } catch (\moodle_exception $e) {
 233              $this->assertInstanceOf('invalid_parameter_exception', $e);
 234              $this->assertSame('Invalid parameter value detected (Invalid context level = -10)', $e->getMessage());
 235          }
 236      }
 237  
 238      /**
 239       * Test \core_external\external_api::get_context()_from_params parameter validation.
 240       *
 241       * @covers \core_external\external_api::get_context
 242       */
 243      public function test_get_context_params(): void {
 244          global $USER;
 245  
 246          // Call without correct context details.
 247          $this->expectException('invalid_parameter_exception');
 248          $this->get_context_from_params(['roleid' => 3, 'userid' => $USER->id]);
 249      }
 250  
 251      /**
 252       * Test \core_external\external_api::get_context()_from_params parameter validation.
 253       *
 254       * @covers \core_external\external_api::get_context
 255       */
 256      public function test_get_context_params2(): void {
 257          global $USER;
 258  
 259          // Call without correct context details.
 260          $this->expectException('invalid_parameter_exception');
 261          $this->get_context_from_params(['roleid' => 3, 'userid' => $USER->id, 'contextlevel' => "course"]);
 262      }
 263  
 264      /**
 265       * Test \core_external\external_api::get_context()_from_params parameter validation.
 266       * @covers \core_external\external_api::get_context
 267       */
 268      public function test_get_context_params3(): void {
 269          global $USER;
 270  
 271          // Call without correct context details.
 272          $this->resetAfterTest(true);
 273          $course = self::getDataGenerator()->create_course();
 274          $this->expectException('invalid_parameter_exception');
 275          $this->get_context_from_params(['roleid' => 3, 'userid' => $USER->id, 'instanceid' => $course->id]);
 276      }
 277  
 278      /**
 279       * Data provider for the test_all_external_info test.
 280       *
 281       * @return array
 282       */
 283      public function all_external_info_provider(): array {
 284          global $DB;
 285  
 286          // We are testing here that all the external function descriptions can be generated without
 287          // producing warnings. E.g. misusing optional params will generate a debugging message which
 288          // will fail this test.
 289          $functions = $DB->get_records('external_functions', [], 'name');
 290          $return = [];
 291          foreach ($functions as $f) {
 292              $return[$f->name] = [$f];
 293          }
 294          return $return;
 295      }
 296  
 297      /**
 298       * Test \core_external\external_api::external_function_info.
 299       *
 300       * @runInSeparateProcess
 301       * @dataProvider all_external_info_provider
 302       * @covers \core_external\external_api::external_function_info
 303       * @param \stdClass $definition
 304       */
 305      public function test_all_external_info(\stdClass $definition): void {
 306          $desc = external_api::external_function_info($definition);
 307          $this->assertNotEmpty($desc->name);
 308          $this->assertNotEmpty($desc->classname);
 309          $this->assertNotEmpty($desc->methodname);
 310          $this->assertEquals($desc->component, clean_param($desc->component, PARAM_COMPONENT));
 311          $this->assertInstanceOf(external_function_parameters::class, $desc->parameters_desc);
 312          if ($desc->returns_desc != null) {
 313              $this->assertInstanceOf(external_description::class, $desc->returns_desc);
 314          }
 315      }
 316  
 317      /**
 318       * Test the \core_external\external_api::call_external_function() function.
 319       *
 320       * @covers \core_external\external_api::call_external_function
 321       */
 322      public function test_call_external_function(): void {
 323          global $PAGE, $COURSE, $CFG;
 324  
 325          $this->resetAfterTest(true);
 326  
 327          // Call some webservice functions and verify they are correctly handling $PAGE and $COURSE.
 328          // First test a function that calls validate_context outside a course.
 329          $this->setAdminUser();
 330          $category = $this->getDataGenerator()->create_category();
 331          $params = [
 332              'contextid' => \context_coursecat::instance($category->id)->id,
 333              'name' => 'aaagrrryyy',
 334              'idnumber' => '',
 335              'description' => '',
 336          ];
 337          $cohort1 = $this->getDataGenerator()->create_cohort($params);
 338          $cohort2 = $this->getDataGenerator()->create_cohort();
 339  
 340          $beforepage = $PAGE;
 341          $beforecourse = $COURSE;
 342          $params = ['cohortids' => [$cohort1->id, $cohort2->id]];
 343          $result = external_api::call_external_function('core_cohort_get_cohorts', $params);
 344  
 345          $this->assertSame($beforepage, $PAGE);
 346          $this->assertSame($beforecourse, $COURSE);
 347  
 348          // Now test a function that calls validate_context inside a course.
 349          $course = $this->getDataGenerator()->create_course();
 350  
 351          $beforepage = $PAGE;
 352          $beforecourse = $COURSE;
 353          $params = ['courseid' => $course->id, 'options' => []];
 354          $result = external_api::call_external_function('core_enrol_get_enrolled_users', $params);
 355  
 356          $this->assertSame($beforepage, $PAGE);
 357          $this->assertSame($beforecourse, $COURSE);
 358  
 359          // Test a function that triggers a PHP exception.
 360          require_once($CFG->dirroot . '/lib/tests/fixtures/test_external_function_throwable.php');
 361  
 362          // Call our test function.
 363          $result = \test_external_function_throwable::call_external_function('core_throw_exception', [], false);
 364  
 365          $this->assertTrue($result['error']);
 366          $this->assertArrayHasKey('exception', $result);
 367          $this->assertEquals($result['exception']->message, 'Exception - Modulo by zero');
 368      }
 369  
 370      /**
 371       * Call the get_contect_from_params methods on the api class.
 372       *
 373       * @return mixed
 374       */
 375      protected function get_context_from_params() {
 376          $rc = new \ReflectionClass(external_api::class);
 377          $method = $rc->getMethod('get_context_from_params');
 378          $method->setAccessible(true);
 379          return $method->invokeArgs(null, func_get_args());
 380      }
 381  }