[Summary view] [Print] [Text view]

   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  /**
  18   * Unit tests for /lib/externallib.php.
  19   *
  20   * @package    core
  21   * @subpackage phpunit
  22   * @copyright  2009 Petr Skoda {@link http://skodak.org}
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  global $CFG;
  29  require_once($CFG->libdir . '/externallib.php');
  30  
  31  
  32  class core_externallib_testcase extends advanced_testcase {
  33      protected $DB;
  34  
  35      public function setUp() {
  36          $this->DB = null;
  37      }
  38  
  39      public function tearDown() {
  40          global $DB;
  41          if ($this->DB !== null) {
  42              $DB = $this->DB;
  43          }
  44      }
  45  
  46      public function test_validate_params() {
  47          $params = array('text'=>'aaa', 'someid'=>'6');
  48          $description = new external_function_parameters(array('someid' => new external_value(PARAM_INT, 'Some int value'),
  49              'text'   => new external_value(PARAM_ALPHA, 'Some text value')));
  50          $result = external_api::validate_parameters($description, $params);
  51          $this->assertCount(2, $result);
  52          reset($result);
  53          $this->assertSame('someid', key($result));
  54          $this->assertSame(6, $result['someid']);
  55          $this->assertSame('aaa', $result['text']);
  56  
  57          $params = array('someids'=>array('1', 2, 'a'=>'3'), 'scalar'=>666);
  58          $description = new external_function_parameters(array('someids' => new external_multiple_structure(new external_value(PARAM_INT, 'Some ID')),
  59              'scalar'  => new external_value(PARAM_ALPHANUM, 'Some text value')));
  60          $result = external_api::validate_parameters($description, $params);
  61          $this->assertCount(2, $result);
  62          reset($result);
  63          $this->assertSame('someids', key($result));
  64          $this->assertEquals(array(0=>1, 1=>2, 2=>3), $result['someids']);
  65          $this->assertSame('666', $result['scalar']);
  66  
  67          $params = array('text'=>'aaa');
  68          $description = new external_function_parameters(array('someid' => new external_value(PARAM_INT, 'Some int value', false),
  69              'text'   => new external_value(PARAM_ALPHA, 'Some text value')));
  70          $result = external_api::validate_parameters($description, $params);
  71          $this->assertCount(2, $result);
  72          reset($result);
  73          $this->assertSame('someid', key($result));
  74          $this->assertNull($result['someid']);
  75          $this->assertSame('aaa', $result['text']);
  76  
  77          $params = array('text'=>'aaa');
  78          $description = new external_function_parameters(array('someid' => new external_value(PARAM_INT, 'Some int value', false, 6),
  79              'text'   => new external_value(PARAM_ALPHA, 'Some text value')));
  80          $result = external_api::validate_parameters($description, $params);
  81          $this->assertCount(2, $result);
  82          reset($result);
  83          $this->assertSame('someid', key($result));
  84          $this->assertSame(6, $result['someid']);
  85          $this->assertSame('aaa', $result['text']);
  86      }
  87  
  88      public function test_external_format_text() {
  89          $settings = external_settings::get_instance();
  90  
  91          $currentraw = $settings->get_raw();
  92          $currentfilter = $settings->get_filter();
  93  
  94          $settings->set_raw(true);
  95          $settings->set_filter(false);
  96          $context = context_system::instance();
  97  
  98          $test = '$$ \pi $$';
  99          $testformat = FORMAT_MARKDOWN;
 100          $correct = array($test, $testformat);
 101          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0), $correct);
 102  
 103          $settings->set_raw(false);
 104          $settings->set_filter(true);
 105  
 106          $test = '$$ \pi $$';
 107          $testformat = FORMAT_MARKDOWN;
 108          $correct = array('<span class="filter_mathjaxloader_equation"><p><span class="nolink">$$ \pi $$</span></p>
 109  </span>', FORMAT_HTML);
 110          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0), $correct);
 111  
 112          // Filters can be opted out from by the developer.
 113          $test = '$$ \pi $$';
 114          $testformat = FORMAT_MARKDOWN;
 115          $correct = array('<p>$$ \pi $$</p>
 116  ', FORMAT_HTML);
 117          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, ['filter' => false]), $correct);
 118  
 119          $test = '<p><a id="test"></a><a href="#test">Text</a></p>';
 120          $testformat = FORMAT_HTML;
 121          $correct = array($test, FORMAT_HTML);
 122          $options = array('allowid' => true);
 123          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, $options), $correct);
 124  
 125          $test = '<p><a id="test"></a><a href="#test">Text</a></p>';
 126          $testformat = FORMAT_HTML;
 127          $correct = array('<p><a></a><a href="#test">Text</a></p>', FORMAT_HTML);
 128          $options = new StdClass();
 129          $options->allowid = false;
 130          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, $options), $correct);
 131  
 132          $test = '<p><a id="test"></a><a href="#test">Text</a></p>'."\n".'Newline';
 133          $testformat = FORMAT_MOODLE;
 134          $correct = array('<p><a id="test"></a><a href="#test">Text</a></p> Newline', FORMAT_HTML);
 135          $options = new StdClass();
 136          $options->newlines = false;
 137          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, $options), $correct);
 138  
 139          $test = '<p><a id="test"></a><a href="#test">Text</a></p>';
 140          $testformat = FORMAT_MOODLE;
 141          $correct = array('<div class="text_to_html">'.$test.'</div>', FORMAT_HTML);
 142          $options = new StdClass();
 143          $options->para = true;
 144          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, $options), $correct);
 145  
 146          $test = '<p><a id="test"></a><a href="#test">Text</a></p>';
 147          $testformat = FORMAT_MOODLE;
 148          $correct = array($test, FORMAT_HTML);
 149          $options = new StdClass();
 150          $options->context = $context;
 151          $this->assertSame(external_format_text($test, $testformat, $context->id, 'core', '', 0, $options), $correct);
 152  
 153          $settings->set_raw($currentraw);
 154          $settings->set_filter($currentfilter);
 155      }
 156  
 157      public function test_external_format_string() {
 158          $this->resetAfterTest();
 159          $settings = external_settings::get_instance();
 160          $currentraw = $settings->get_raw();
 161          $currentfilter = $settings->get_filter();
 162  
 163          // Enable multilang filter to on content and heading.
 164          filter_set_global_state('multilang', TEXTFILTER_ON);
 165          filter_set_applies_to_strings('multilang', 1);
 166          $filtermanager = filter_manager::instance();
 167          $filtermanager->reset_caches();
 168  
 169          $settings->set_raw(true);
 170          $settings->set_filter(true);
 171          $context = context_system::instance();
 172  
 173          $test = '<span lang="en" class="multilang">EN</span><span lang="fr" class="multilang">FR</span> ' .
 174              '<script>hi</script> <h3>there</h3>!';
 175          $correct = $test;
 176          $this->assertSame($correct, external_format_string($test, $context->id));
 177  
 178          $settings->set_raw(false);
 179          $settings->set_filter(false);
 180  
 181          $test = '<span lang="en" class="multilang">EN</span><span lang="fr" class="multilang">FR</span> ' .
 182              '<script>hi</script> <h3>there</h3>?';
 183          $correct = 'ENFR hi there?';
 184          $this->assertSame($correct, external_format_string($test, $context->id));
 185  
 186          $settings->set_filter(true);
 187  
 188          $test = '<span lang="en" class="multilang">EN</span><span lang="fr" class="multilang">FR</span> ' .
 189              '<script>hi</script> <h3>there</h3>@';
 190          $correct = 'EN hi there@';
 191          $this->assertSame($correct, external_format_string($test, $context->id));
 192  
 193          // Filters can be opted out.
 194          $test = '<span lang="en" class="multilang">EN</span><span lang="fr" class="multilang">FR</span> ' .
 195              '<script>hi</script> <h3>there</h3>%';
 196          $correct = 'ENFR hi there%';
 197          $this->assertSame($correct, external_format_string($test, $context->id, false, ['filter' => false]));
 198  
 199          $this->assertSame("& < > \" '", format_string("& < > \" '", true, ['escape' => false]));
 200  
 201          $settings->set_raw($currentraw);
 202          $settings->set_filter($currentfilter);
 203      }
 204  
 205      /**
 206       * Test for clean_returnvalue().
 207       */
 208      public function test_clean_returnvalue() {
 209  
 210          // Build some return value decription.
 211          $returndesc = new external_multiple_structure(
 212              new external_single_structure(
 213                  array(
 214                      'object' => new external_single_structure(
 215                                  array('value1' => new external_value(PARAM_INT, 'this is a int'))),
 216                      'value2' => new external_value(PARAM_TEXT, 'some text', VALUE_OPTIONAL))
 217              ));
 218  
 219          // Clean an object (it should be cast into an array).
 220          $object = new stdClass();
 221          $object->value1 = 1;
 222          $singlestructure['object'] = $object;
 223          $singlestructure['value2'] = 'Some text';
 224          $testdata = array($singlestructure);
 225          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 226          $cleanedsinglestructure = array_pop($cleanedvalue);
 227          $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
 228          $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
 229  
 230          // Missing VALUE_OPTIONAL.
 231          $object = new stdClass();
 232          $object->value1 = 1;
 233          $singlestructure = new stdClass();
 234          $singlestructure->object = $object;
 235          $testdata = array($singlestructure);
 236          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 237          $cleanedsinglestructure = array_pop($cleanedvalue);
 238          $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
 239          $this->assertArrayNotHasKey('value2', $cleanedsinglestructure);
 240  
 241          // Unknown attribute (the value should be ignored).
 242          $object = array();
 243          $object['value1'] = 1;
 244          $singlestructure = array();
 245          $singlestructure['object'] = $object;
 246          $singlestructure['value2'] = 'Some text';
 247          $singlestructure['unknownvalue'] = 'Some text to ignore';
 248          $testdata = array($singlestructure);
 249          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 250          $cleanedsinglestructure = array_pop($cleanedvalue);
 251          $this->assertSame($object['value1'], $cleanedsinglestructure['object']['value1']);
 252          $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
 253          $this->assertArrayNotHasKey('unknownvalue', $cleanedsinglestructure);
 254  
 255          // Missing required value (an exception is thrown).
 256          $object = array();
 257          $singlestructure = array();
 258          $singlestructure['object'] = $object;
 259          $singlestructure['value2'] = 'Some text';
 260          $testdata = array($singlestructure);
 261          $this->expectException('invalid_response_exception');
 262          $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
 263      }
 264      /*
 265       * Test external_api::get_context_from_params().
 266       */
 267      public function test_get_context_from_params() {
 268          $this->resetAfterTest(true);
 269          $course = $this->getDataGenerator()->create_course();
 270          $realcontext = context_course::instance($course->id);
 271  
 272          // Use context id.
 273          $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => $realcontext->id));
 274          $this->assertEquals($realcontext, $fetchedcontext);
 275  
 276          // Use context level and instance id.
 277          $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "course", "instanceid" => $course->id));
 278          $this->assertEquals($realcontext, $fetchedcontext);
 279  
 280          // Passing empty values.
 281          try {
 282              $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => 0));
 283              $this->fail('Exception expected from get_context_wrapper()');
 284          } catch (moodle_exception $e) {
 285              $this->assertInstanceOf('invalid_parameter_exception', $e);
 286          }
 287  
 288          try {
 289              $fetchedcontext = test_exernal_api::get_context_wrapper(array("instanceid" => 0));
 290              $this->fail('Exception expected from get_context_wrapper()');
 291          } catch (moodle_exception $e) {
 292              $this->assertInstanceOf('invalid_parameter_exception', $e);
 293          }
 294  
 295          try {
 296              $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => null));
 297              $this->fail('Exception expected from get_context_wrapper()');
 298          } catch (moodle_exception $e) {
 299              $this->assertInstanceOf('invalid_parameter_exception', $e);
 300          }
 301  
 302          // Tests for context with instanceid equal to 0 (System context).
 303          $realcontext = context_system::instance();
 304          $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "system", "instanceid" => 0));
 305          $this->assertEquals($realcontext, $fetchedcontext);
 306  
 307          // Passing wrong level.
 308          $this->expectException('invalid_parameter_exception');
 309          $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "random", "instanceid" => $course->id));
 310      }
 311  
 312      /*
 313       * Test external_api::get_context()_from_params parameter validation.
 314       */
 315      public function test_get_context_params() {
 316          global $USER;
 317  
 318          // Call without correct context details.
 319          $this->expectException('invalid_parameter_exception');
 320          test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id));
 321      }
 322  
 323      /*
 324       * Test external_api::get_context()_from_params parameter validation.
 325       */
 326      public function test_get_context_params2() {
 327          global $USER;
 328  
 329          // Call without correct context details.
 330          $this->expectException('invalid_parameter_exception');
 331          test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id, 'contextlevel' => "course"));
 332      }
 333  
 334      /*
 335       * Test external_api::get_context()_from_params parameter validation.
 336       */
 337      public function test_get_context_params3() {
 338          global $USER;
 339  
 340          // Call without correct context details.
 341          $this->resetAfterTest(true);
 342          $course = self::getDataGenerator()->create_course();
 343          $this->expectException('invalid_parameter_exception');
 344          test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id, 'instanceid' => $course->id));
 345      }
 346  
 347      public function all_external_info_provider() {
 348          global $DB;
 349  
 350          // We are testing here that all the external function descriptions can be generated without
 351          // producing warnings. E.g. misusing optional params will generate a debugging message which
 352          // will fail this test.
 353          $functions = $DB->get_records('external_functions', array(), 'name');
 354          $return = array();
 355          foreach ($functions as $f) {
 356              $return[$f->name] = array($f);
 357          }
 358          return $return;
 359      }
 360  
 361      /**
 362       * @dataProvider all_external_info_provider
 363       */
 364      public function test_all_external_info($f) {
 365          $desc = external_api::external_function_info($f);
 366          $this->assertNotEmpty($desc->name);
 367          $this->assertNotEmpty($desc->classname);
 368          $this->assertNotEmpty($desc->methodname);
 369          $this->assertEquals($desc->component, clean_param($desc->component, PARAM_COMPONENT));
 370          $this->assertInstanceOf('external_function_parameters', $desc->parameters_desc);
 371          if ($desc->returns_desc != null) {
 372              $this->assertInstanceOf('external_description', $desc->returns_desc);
 373          }
 374      }
 375  
 376      public function test_validate_courses() {
 377          $this->resetAfterTest(true);
 378  
 379          $c1 = $this->getDataGenerator()->create_course();
 380          $c2 = $this->getDataGenerator()->create_course();
 381          $c3 = $this->getDataGenerator()->create_course();
 382          $u1 = $this->getDataGenerator()->create_user();
 383          $this->getDataGenerator()->enrol_user($u1->id, $c1->id);
 384          $courseids = array($c1->id, $c2->id, $c3->id);
 385  
 386          $this->setAdminUser();
 387          list($courses, $warnings) = external_util::validate_courses($courseids);
 388          $this->assertEmpty($warnings);
 389          $this->assertCount(3, $courses);
 390          $this->assertArrayHasKey($c1->id, $courses);
 391          $this->assertArrayHasKey($c2->id, $courses);
 392          $this->assertArrayHasKey($c3->id, $courses);
 393          $this->assertEquals($c1->id, $courses[$c1->id]->id);
 394          $this->assertEquals($c2->id, $courses[$c2->id]->id);
 395          $this->assertEquals($c3->id, $courses[$c3->id]->id);
 396  
 397          $this->setUser($u1);
 398          list($courses, $warnings) = external_util::validate_courses($courseids);
 399          $this->assertCount(2, $warnings);
 400          $this->assertEquals($c2->id, $warnings[0]['itemid']);
 401          $this->assertEquals($c3->id, $warnings[1]['itemid']);
 402          $this->assertCount(1, $courses);
 403          $this->assertArrayHasKey($c1->id, $courses);
 404          $this->assertArrayNotHasKey($c2->id, $courses);
 405          $this->assertArrayNotHasKey($c3->id, $courses);
 406          $this->assertEquals($c1->id, $courses[$c1->id]->id);
 407      }
 408  
 409      /**
 410       * Validate courses can re-use an array of prefetched courses.
 411       */
 412      public function test_validate_courses_prefetch() {
 413          $this->resetAfterTest(true);
 414  
 415          $c1 = $this->getDataGenerator()->create_course();
 416          $c2 = $this->getDataGenerator()->create_course();
 417          $c3 = $this->getDataGenerator()->create_course();
 418          $c4 = $this->getDataGenerator()->create_course();
 419          $u1 = $this->getDataGenerator()->create_user();
 420          $this->getDataGenerator()->enrol_user($u1->id, $c1->id);
 421          $this->getDataGenerator()->enrol_user($u1->id, $c2->id);
 422  
 423          $courseids = array($c1->id, $c2->id, $c3->id);
 424          $courses = array($c2->id => $c2, $c3->id => $c3, $c4->id => $c4);
 425  
 426          $this->setUser($u1);
 427          list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
 428          $this->assertCount(2, $courses);
 429          $this->assertCount(1, $warnings);
 430          $this->assertArrayHasKey($c1->id, $courses);
 431          $this->assertSame($c2, $courses[$c2->id]);
 432          $this->assertArrayNotHasKey($c3->id, $courses);
 433          // The extra course passed is not returned.
 434          $this->assertArrayNotHasKey($c4->id, $courses);
 435      }
 436  
 437  
 438      public function test_call_external_function() {
 439          global $PAGE, $COURSE;
 440  
 441          $this->resetAfterTest(true);
 442  
 443          // Call some webservice functions and verify they are correctly handling $PAGE and $COURSE.
 444          // First test a function that calls validate_context outside a course.
 445          $this->setAdminUser();
 446          $category = $this->getDataGenerator()->create_category();
 447          $params = array(
 448              'contextid' => context_coursecat::instance($category->id)->id,
 449              'name' => 'aaagrrryyy',
 450              'idnumber' => '',
 451              'description' => ''
 452          );
 453          $cohort1 = $this->getDataGenerator()->create_cohort($params);
 454          $cohort2 = $this->getDataGenerator()->create_cohort();
 455  
 456          $beforepage = $PAGE;
 457          $beforecourse = $COURSE;
 458          $params = array('cohortids' => array($cohort1->id, $cohort2->id));
 459          $result = external_api::call_external_function('core_cohort_get_cohorts', $params);
 460  
 461          $this->assertSame($beforepage, $PAGE);
 462          $this->assertSame($beforecourse, $COURSE);
 463  
 464          // Now test a function that calls validate_context inside a course.
 465          $course = $this->getDataGenerator()->create_course();
 466  
 467          $beforepage = $PAGE;
 468          $beforecourse = $COURSE;
 469          $params = array('courseid' => $course->id, 'options' => array());
 470          $result = external_api::call_external_function('core_enrol_get_enrolled_users', $params);
 471  
 472          $this->assertSame($beforepage, $PAGE);
 473          $this->assertSame($beforecourse, $COURSE);
 474      }
 475  
 476      /**
 477       * Text external_util::get_area_files
 478       */
 479      public function test_external_util_get_area_files() {
 480          global $CFG, $DB;
 481  
 482          $this->DB = $DB;
 483          $DB = $this->getMockBuilder('moodle_database')->getMock();
 484  
 485          $content = base64_encode("Let us create a nice simple file.");
 486          $timemodified = 102030405;
 487          $itemid = 42;
 488          $filesize = strlen($content);
 489  
 490          $DB->method('get_records_sql')->willReturn([
 491              (object) [
 492                  'filename'      => 'example.txt',
 493                  'filepath'      => '/',
 494                  'mimetype'      => 'text/plain',
 495                  'filesize'      => $filesize,
 496                  'timemodified'  => $timemodified,
 497                  'itemid'        => $itemid,
 498                  'pathnamehash'  => sha1('/example.txt'),
 499              ],
 500          ]);
 501  
 502          $component = 'mod_foo';
 503          $filearea = 'area';
 504          $context = 12345;
 505  
 506          $expectedfiles[] = array(
 507              'filename' => 'example.txt',
 508              'filepath' => '/',
 509              'fileurl' => "{$CFG->wwwroot}/webservice/pluginfile.php/{$context}/{$component}/{$filearea}/{$itemid}/example.txt",
 510              'timemodified' => $timemodified,
 511              'filesize' => $filesize,
 512              'mimetype' => 'text/plain',
 513          );
 514          // Get all the files for the area.
 515          $files = external_util::get_area_files($context, $component, $filearea, false);
 516          $this->assertEquals($expectedfiles, $files);
 517  
 518          // Get just the file indicated by $itemid.
 519          $files = external_util::get_area_files($context, $component, $filearea, $itemid);
 520          $this->assertEquals($expectedfiles, $files);
 521  
 522      }
 523  
 524      /**
 525       * Text external files structure.
 526       */
 527      public function test_external_files() {
 528  
 529          $description = new external_files();
 530  
 531          // First check that the expected default values and keys are returned.
 532          $expectedkeys = array_flip(array('filename', 'filepath', 'filesize', 'fileurl', 'timemodified', 'mimetype'));
 533          $returnedkeys = array_flip(array_keys($description->content->keys));
 534          $this->assertEquals($expectedkeys, $returnedkeys);
 535          $this->assertEquals('List of files.', $description->desc);
 536          $this->assertEquals(VALUE_REQUIRED, $description->required);
 537          foreach ($description->content->keys as $key) {
 538              $this->assertEquals(VALUE_OPTIONAL, $key->required);
 539          }
 540  
 541      }
 542  
 543  }
 544  
 545  /*
 546   * Just a wrapper to access protected apis for testing
 547   */
 548  class test_exernal_api extends external_api {
 549  
 550      public static function get_context_wrapper($params) {
 551          return self::get_context_from_params($params);
 552      }
 553  }