Merge branch 'MDL-55007-master' of https://github.com/dthies/moodle
[moodle.git] / lib / tests / externallib_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/>.
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  */
26 defined('MOODLE_INTERNAL') || die();
28 global $CFG;
29 require_once($CFG->libdir . '/externallib.php');
32 class core_externallib_testcase extends advanced_testcase {
33     protected $DB;
35     public function setUp() {
36         $this->DB = null;
37     }
39     public function tearDown() {
40         global $DB;
41         if ($this->DB !== null) {
42             $DB = $this->DB;
43         }
44     }
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']);
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']);
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']);
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     }
88     public function test_external_format_text() {
89         $settings = external_settings::get_instance();
91         $currentraw = $settings->get_raw();
92         $currentfilter = $settings->get_filter();
94         $settings->set_raw(true);
95         $settings->set_filter(false);
96         $context = context_system::instance();
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);
103         $settings->set_raw(false);
104         $settings->set_filter(true);
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);
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);
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);
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);
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);
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);
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);
153         $settings->set_raw($currentraw);
154         $settings->set_filter($currentfilter);
155     }
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();
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();
169         $settings->set_raw(true);
170         $settings->set_filter(true);
171         $context = context_system::instance();
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));
178         $settings->set_raw(false);
179         $settings->set_filter(false);
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));
186         $settings->set_filter(true);
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));
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]));
200         $settings->set_raw($currentraw);
201         $settings->set_filter($currentfilter);
202     }
204     /**
205      * Test for clean_returnvalue().
206      */
207     public function test_clean_returnvalue() {
209         // Build some return value decription.
210         $returndesc = new external_multiple_structure(
211             new external_single_structure(
212                 array(
213                     'object' => new external_single_structure(
214                                 array('value1' => new external_value(PARAM_INT, 'this is a int'))),
215                     'value2' => new external_value(PARAM_TEXT, 'some text', VALUE_OPTIONAL))
216             ));
218         // Clean an object (it should be cast into an array).
219         $object = new stdClass();
220         $object->value1 = 1;
221         $singlestructure['object'] = $object;
222         $singlestructure['value2'] = 'Some text';
223         $testdata = array($singlestructure);
224         $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
225         $cleanedsinglestructure = array_pop($cleanedvalue);
226         $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
227         $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
229         // Missing VALUE_OPTIONAL.
230         $object = new stdClass();
231         $object->value1 = 1;
232         $singlestructure = new stdClass();
233         $singlestructure->object = $object;
234         $testdata = array($singlestructure);
235         $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
236         $cleanedsinglestructure = array_pop($cleanedvalue);
237         $this->assertSame($object->value1, $cleanedsinglestructure['object']['value1']);
238         $this->assertArrayNotHasKey('value2', $cleanedsinglestructure);
240         // Unknown attribute (the value should be ignored).
241         $object = array();
242         $object['value1'] = 1;
243         $singlestructure = array();
244         $singlestructure['object'] = $object;
245         $singlestructure['value2'] = 'Some text';
246         $singlestructure['unknownvalue'] = 'Some text to ignore';
247         $testdata = array($singlestructure);
248         $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
249         $cleanedsinglestructure = array_pop($cleanedvalue);
250         $this->assertSame($object['value1'], $cleanedsinglestructure['object']['value1']);
251         $this->assertSame($singlestructure['value2'], $cleanedsinglestructure['value2']);
252         $this->assertArrayNotHasKey('unknownvalue', $cleanedsinglestructure);
254         // Missing required value (an exception is thrown).
255         $object = array();
256         $singlestructure = array();
257         $singlestructure['object'] = $object;
258         $singlestructure['value2'] = 'Some text';
259         $testdata = array($singlestructure);
260         $this->setExpectedException('invalid_response_exception');
261         $cleanedvalue = external_api::clean_returnvalue($returndesc, $testdata);
262     }
263     /*
264      * Test external_api::get_context_from_params().
265      */
266     public function test_get_context_from_params() {
267         $this->resetAfterTest(true);
268         $course = $this->getDataGenerator()->create_course();
269         $realcontext = context_course::instance($course->id);
271         // Use context id.
272         $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => $realcontext->id));
273         $this->assertEquals($realcontext, $fetchedcontext);
275         // Use context level and instance id.
276         $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "course", "instanceid" => $course->id));
277         $this->assertEquals($realcontext, $fetchedcontext);
279         // Passing empty values.
280         try {
281             $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => 0));
282             $this->fail('Exception expected from get_context_wrapper()');
283         } catch (moodle_exception $e) {
284             $this->assertInstanceOf('invalid_parameter_exception', $e);
285         }
287         try {
288             $fetchedcontext = test_exernal_api::get_context_wrapper(array("instanceid" => 0));
289             $this->fail('Exception expected from get_context_wrapper()');
290         } catch (moodle_exception $e) {
291             $this->assertInstanceOf('invalid_parameter_exception', $e);
292         }
294         try {
295             $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextid" => null));
296             $this->fail('Exception expected from get_context_wrapper()');
297         } catch (moodle_exception $e) {
298             $this->assertInstanceOf('invalid_parameter_exception', $e);
299         }
301         // Tests for context with instanceid equal to 0 (System context).
302         $realcontext = context_system::instance();
303         $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "system", "instanceid" => 0));
304         $this->assertEquals($realcontext, $fetchedcontext);
306         // Passing wrong level.
307         $this->setExpectedException('invalid_parameter_exception');
308         $fetchedcontext = test_exernal_api::get_context_wrapper(array("contextlevel" => "random", "instanceid" => $course->id));
309     }
311     /*
312      * Test external_api::get_context()_from_params parameter validation.
313      */
314     public function test_get_context_params() {
315         global $USER;
317         // Call without correct context details.
318         $this->setExpectedException('invalid_parameter_exception');
319         test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id));
320     }
322     /*
323      * Test external_api::get_context()_from_params parameter validation.
324      */
325     public function test_get_context_params2() {
326         global $USER;
328         // Call without correct context details.
329         $this->setExpectedException('invalid_parameter_exception');
330         test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id, 'contextlevel' => "course"));
331     }
333     /*
334      * Test external_api::get_context()_from_params parameter validation.
335      */
336     public function test_get_context_params3() {
337         global $USER;
339         // Call without correct context details.
340         $this->resetAfterTest(true);
341         $course = self::getDataGenerator()->create_course();
342         $this->setExpectedException('invalid_parameter_exception');
343         test_exernal_api::get_context_wrapper(array('roleid' => 3, 'userid' => $USER->id, 'instanceid' => $course->id));
344     }
346     public function all_external_info_provider() {
347         global $DB;
349         // We are testing here that all the external function descriptions can be generated without
350         // producing warnings. E.g. misusing optional params will generate a debugging message which
351         // will fail this test.
352         $functions = $DB->get_records('external_functions', array(), 'name');
353         $return = array();
354         foreach ($functions as $f) {
355             $return[$f->name] = array($f);
356         }
357         return $return;
358     }
360     /**
361      * @dataProvider all_external_info_provider
362      */
363     public function test_all_external_info($f) {
364         $desc = external_api::external_function_info($f);
365         $this->assertNotEmpty($desc->name);
366         $this->assertNotEmpty($desc->classname);
367         $this->assertNotEmpty($desc->methodname);
368         $this->assertEquals($desc->component, clean_param($desc->component, PARAM_COMPONENT));
369         $this->assertInstanceOf('external_function_parameters', $desc->parameters_desc);
370         if ($desc->returns_desc != null) {
371             $this->assertInstanceOf('external_description', $desc->returns_desc);
372         }
373     }
375     public function test_validate_courses() {
376         $this->resetAfterTest(true);
378         $c1 = $this->getDataGenerator()->create_course();
379         $c2 = $this->getDataGenerator()->create_course();
380         $c3 = $this->getDataGenerator()->create_course();
381         $u1 = $this->getDataGenerator()->create_user();
382         $this->getDataGenerator()->enrol_user($u1->id, $c1->id);
383         $courseids = array($c1->id, $c2->id, $c3->id);
385         $this->setAdminUser();
386         list($courses, $warnings) = external_util::validate_courses($courseids);
387         $this->assertEmpty($warnings);
388         $this->assertCount(3, $courses);
389         $this->assertArrayHasKey($c1->id, $courses);
390         $this->assertArrayHasKey($c2->id, $courses);
391         $this->assertArrayHasKey($c3->id, $courses);
392         $this->assertEquals($c1->id, $courses[$c1->id]->id);
393         $this->assertEquals($c2->id, $courses[$c2->id]->id);
394         $this->assertEquals($c3->id, $courses[$c3->id]->id);
396         $this->setUser($u1);
397         list($courses, $warnings) = external_util::validate_courses($courseids);
398         $this->assertCount(2, $warnings);
399         $this->assertEquals($c2->id, $warnings[0]['itemid']);
400         $this->assertEquals($c3->id, $warnings[1]['itemid']);
401         $this->assertCount(1, $courses);
402         $this->assertArrayHasKey($c1->id, $courses);
403         $this->assertArrayNotHasKey($c2->id, $courses);
404         $this->assertArrayNotHasKey($c3->id, $courses);
405         $this->assertEquals($c1->id, $courses[$c1->id]->id);
406     }
408     /**
409      * Validate courses can re-use an array of prefetched courses.
410      */
411     public function test_validate_courses_prefetch() {
412         $this->resetAfterTest(true);
414         $c1 = $this->getDataGenerator()->create_course();
415         $c2 = $this->getDataGenerator()->create_course();
416         $c3 = $this->getDataGenerator()->create_course();
417         $c4 = $this->getDataGenerator()->create_course();
418         $u1 = $this->getDataGenerator()->create_user();
419         $this->getDataGenerator()->enrol_user($u1->id, $c1->id);
420         $this->getDataGenerator()->enrol_user($u1->id, $c2->id);
422         $courseids = array($c1->id, $c2->id, $c3->id);
423         $courses = array($c2->id => $c2, $c3->id => $c3, $c4->id => $c4);
425         $this->setUser($u1);
426         list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
427         $this->assertCount(2, $courses);
428         $this->assertCount(1, $warnings);
429         $this->assertArrayHasKey($c1->id, $courses);
430         $this->assertSame($c2, $courses[$c2->id]);
431         $this->assertArrayNotHasKey($c3->id, $courses);
432         // The extra course passed is not returned.
433         $this->assertArrayNotHasKey($c4->id, $courses);
434     }
437     public function test_call_external_function() {
438         global $PAGE, $COURSE;
440         $this->resetAfterTest(true);
442         // Call some webservice functions and verify they are correctly handling $PAGE and $COURSE.
443         // First test a function that calls validate_context outside a course.
444         $this->setAdminUser();
445         $category = $this->getDataGenerator()->create_category();
446         $params = array(
447             'contextid' => context_coursecat::instance($category->id)->id,
448             'name' => 'aaagrrryyy',
449             'idnumber' => '',
450             'description' => ''
451         );
452         $cohort1 = $this->getDataGenerator()->create_cohort($params);
453         $cohort2 = $this->getDataGenerator()->create_cohort();
455         $beforepage = $PAGE;
456         $beforecourse = $COURSE;
457         $params = array('cohortids' => array($cohort1->id, $cohort2->id));
458         $result = external_api::call_external_function('core_cohort_get_cohorts', $params);
460         $this->assertSame($beforepage, $PAGE);
461         $this->assertSame($beforecourse, $COURSE);
463         // Now test a function that calls validate_context inside a course.
464         $course = $this->getDataGenerator()->create_course();
466         $beforepage = $PAGE;
467         $beforecourse = $COURSE;
468         $params = array('courseid' => $course->id, 'options' => array());
469         $result = external_api::call_external_function('core_enrol_get_enrolled_users', $params);
471         $this->assertSame($beforepage, $PAGE);
472         $this->assertSame($beforecourse, $COURSE);
473     }
475     /**
476      * Text external_util::get_area_files
477      */
478     public function test_external_util_get_area_files() {
479         global $CFG, $DB;
481         $this->DB = $DB;
482         $DB = $this->getMockBuilder('moodle_database')->getMock();
484         $content = base64_encode("Let us create a nice simple file.");
485         $timemodified = 102030405;
486         $itemid = 42;
487         $filesize = strlen($content);
489         $DB->method('get_records_sql')->willReturn([
490             (object) [
491                 'filename'      => 'example.txt',
492                 'filepath'      => '/',
493                 'mimetype'      => 'text/plain',
494                 'filesize'      => $filesize,
495                 'timemodified'  => $timemodified,
496                 'itemid'        => $itemid,
497                 'pathnamehash'  => sha1('/example.txt'),
498             ],
499         ]);
501         $component = 'mod_foo';
502         $filearea = 'area';
503         $context = 12345;
505         $expectedfiles[] = array(
506             'filename' => 'example.txt',
507             'filepath' => '/',
508             'fileurl' => "{$CFG->wwwroot}/webservice/pluginfile.php/{$context}/{$component}/{$filearea}/{$itemid}/example.txt",
509             'timemodified' => $timemodified,
510             'filesize' => $filesize,
511             'mimetype' => 'text/plain',
512         );
513         // Get all the files for the area.
514         $files = external_util::get_area_files($context, $component, $filearea, false);
515         $this->assertEquals($expectedfiles, $files);
517         // Get just the file indicated by $itemid.
518         $files = external_util::get_area_files($context, $component, $filearea, $itemid);
519         $this->assertEquals($expectedfiles, $files);
521     }
523     /**
524      * Text external files structure.
525      */
526     public function test_external_files() {
528         $description = new external_files();
530         // First check that the expected default values and keys are returned.
531         $expectedkeys = array_flip(array('filename', 'filepath', 'filesize', 'fileurl', 'timemodified', 'mimetype'));
532         $returnedkeys = array_flip(array_keys($description->content->keys));
533         $this->assertEquals($expectedkeys, $returnedkeys);
534         $this->assertEquals('List of files.', $description->desc);
535         $this->assertEquals(VALUE_REQUIRED, $description->required);
536         foreach ($description->content->keys as $key) {
537             $this->assertEquals(VALUE_OPTIONAL, $key->required);
538         }
540     }
544 /*
545  * Just a wrapper to access protected apis for testing
546  */
547 class test_exernal_api extends external_api {
549     public static function get_context_wrapper($params) {
550         return self::get_context_from_params($params);
551     }