fc51e267e71e0f82820cfcf75eb9cf36a800c618
[moodle.git] / lib / phpunit / classes / util.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  * Utility class.
19  *
20  * @package    core
21  * @category   phpunit
22  * @copyright  2012 Petr Skoda {@link http://skodak.org}
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 require_once(__DIR__.'/../../testing/classes/util.php');
28 /**
29  * Collection of utility methods.
30  *
31  * @package    core
32  * @category   phpunit
33  * @copyright  2012 Petr Skoda {@link http://skodak.org}
34  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
36 class phpunit_util extends testing_util {
37     /** @var array An array of original globals, restored after each test */
38     protected static $globals = array();
40     /** @var array list of debugging messages triggered during the last test execution */
41     protected static $debuggings = array();
43     /** @var phpunit_message_sink alternative target for moodle messaging */
44     protected static $messagesink = null;
46     /** @var phpunit_phpmailer_sink alternative target for phpmailer messaging */
47     protected static $phpmailersink = null;
49     /** @var phpunit_message_sink alternative target for moodle messaging */
50     protected static $eventsink = null;
52     /**
53      * @var array Files to skip when resetting dataroot folder
54      */
55     protected static $datarootskiponreset = array('.', '..', 'phpunittestdir.txt', 'phpunit', '.htaccess');
57     /**
58      * @var array Files to skip when dropping dataroot folder
59      */
60     protected static $datarootskipondrop = array('.', '..', 'lock', 'webrunner.xml');
62     /**
63      * Load global $CFG;
64      * @internal
65      * @static
66      * @return void
67      */
68     public static function initialise_cfg() {
69         global $DB;
70         $dbhash = false;
71         try {
72             $dbhash = $DB->get_field('config', 'value', array('name'=>'phpunittest'));
73         } catch (Exception $e) {
74             // not installed yet
75             initialise_cfg();
76             return;
77         }
78         if ($dbhash !== core_component::get_all_versions_hash()) {
79             // do not set CFG - the only way forward is to drop and reinstall
80             return;
81         }
82         // standard CFG init
83         initialise_cfg();
84     }
86     /**
87      * Reset contents of all database tables to initial values, reset caches, etc.
88      *
89      * Note: this is relatively slow (cca 2 seconds for pg and 7 for mysql) - please use with care!
90      *
91      * @static
92      * @param bool $detectchanges
93      *      true  - changes in global state and database are reported as errors
94      *      false - no errors reported
95      *      null  - only critical problems are reported as errors
96      * @return void
97      */
98     public static function reset_all_data($detectchanges = false) {
99         global $DB, $CFG, $USER, $SITE, $COURSE, $PAGE, $OUTPUT, $SESSION;
101         // Stop any message redirection.
102         phpunit_util::stop_message_redirection();
104         // Stop any message redirection.
105         phpunit_util::stop_phpmailer_redirection();
107         // Stop any message redirection.
108         phpunit_util::stop_event_redirection();
110         // Release memory and indirectly call destroy() methods to release resource handles, etc.
111         gc_collect_cycles();
113         // Show any unhandled debugging messages, the runbare() could already reset it.
114         self::display_debugging_messages();
115         self::reset_debugging();
117         // reset global $DB in case somebody mocked it
118         $DB = self::get_global_backup('DB');
120         if ($DB->is_transaction_started()) {
121             // we can not reset inside transaction
122             $DB->force_transaction_rollback();
123         }
125         $resetdb = self::reset_database();
126         $warnings = array();
128         if ($detectchanges === true) {
129             if ($resetdb) {
130                 $warnings[] = 'Warning: unexpected database modification, resetting DB state';
131             }
133             $oldcfg = self::get_global_backup('CFG');
134             $oldsite = self::get_global_backup('SITE');
135             foreach($CFG as $k=>$v) {
136                 if (!property_exists($oldcfg, $k)) {
137                     $warnings[] = 'Warning: unexpected new $CFG->'.$k.' value';
138                 } else if ($oldcfg->$k !== $CFG->$k) {
139                     $warnings[] = 'Warning: unexpected change of $CFG->'.$k.' value';
140                 }
141                 unset($oldcfg->$k);
143             }
144             if ($oldcfg) {
145                 foreach($oldcfg as $k=>$v) {
146                     $warnings[] = 'Warning: unexpected removal of $CFG->'.$k;
147                 }
148             }
150             if ($USER->id != 0) {
151                 $warnings[] = 'Warning: unexpected change of $USER';
152             }
154             if ($COURSE->id != $oldsite->id) {
155                 $warnings[] = 'Warning: unexpected change of $COURSE';
156             }
158         }
160         if (ini_get('max_execution_time') != 0) {
161             // This is special warning for all resets because we do not want any
162             // libraries to mess with timeouts unintentionally.
163             // Our PHPUnit integration is not supposed to change it either.
165             if ($detectchanges !== false) {
166                 $warnings[] = 'Warning: max_execution_time was changed to '.ini_get('max_execution_time');
167             }
168             set_time_limit(0);
169         }
171         // restore original globals
172         $_SERVER = self::get_global_backup('_SERVER');
173         $CFG = self::get_global_backup('CFG');
174         $SITE = self::get_global_backup('SITE');
175         $_GET = array();
176         $_POST = array();
177         $_FILES = array();
178         $_REQUEST = array();
179         $COURSE = $SITE;
181         // reinitialise following globals
182         $OUTPUT = new bootstrap_renderer();
183         $PAGE = new moodle_page();
184         $FULLME = null;
185         $ME = null;
186         $SCRIPT = null;
187         $SESSION = new stdClass();
188         $_SESSION['SESSION'] =& $SESSION;
190         // set fresh new not-logged-in user
191         $user = new stdClass();
192         $user->id = 0;
193         $user->mnethostid = $CFG->mnet_localhost_id;
194         \core\session\manager::set_user($user);
196         // reset all static caches
197         \core\event\manager::phpunit_reset();
198         accesslib_clear_all_caches(true);
199         get_string_manager()->reset_caches(true);
200         reset_text_filters_cache(true);
201         events_get_handlers('reset');
202         core_text::reset_caches();
203         get_message_processors(false, true);
204         if (class_exists('repository')) {
205             repository::reset_caches();
206         }
207         filter_manager::reset_caches();
208         //TODO MDL-25290: add more resets here and probably refactor them to new core function
210         // Reset course and module caches.
211         if (class_exists('format_base')) {
212             // If file containing class is not loaded, there is no cache there anyway.
213             format_base::reset_course_cache(0);
214         }
215         get_fast_modinfo(0, 0, true);
217         // Reset other singletons.
218         if (class_exists('core_plugin_manager')) {
219             core_plugin_manager::reset_caches(true);
220         }
221         if (class_exists('\core\update\checker')) {
222             \core\update\checker::reset_caches(true);
223         }
224         if (class_exists('\core\update\deployer')) {
225             \core\update\deployer::reset_caches(true);
226         }
228         // purge dataroot directory
229         self::reset_dataroot();
231         // restore original config once more in case resetting of caches changed CFG
232         $CFG = self::get_global_backup('CFG');
234         // inform data generator
235         self::get_data_generator()->reset();
237         // fix PHP settings
238         error_reporting($CFG->debug);
240         // verify db writes just in case something goes wrong in reset
241         if (self::$lastdbwrites != $DB->perf_get_writes()) {
242             error_log('Unexpected DB writes in phpunit_util::reset_all_data()');
243             self::$lastdbwrites = $DB->perf_get_writes();
244         }
246         if ($warnings) {
247             $warnings = implode("\n", $warnings);
248             trigger_error($warnings, E_USER_WARNING);
249         }
250     }
252     /**
253      * Called during bootstrap only!
254      * @internal
255      * @static
256      * @return void
257      */
258     public static function bootstrap_init() {
259         global $CFG, $SITE, $DB;
261         // backup the globals
262         self::$globals['_SERVER'] = $_SERVER;
263         self::$globals['CFG'] = clone($CFG);
264         self::$globals['SITE'] = clone($SITE);
265         self::$globals['DB'] = $DB;
267         // refresh data in all tables, clear caches, etc.
268         phpunit_util::reset_all_data();
269     }
271     /**
272      * Print some Moodle related info to console.
273      * @internal
274      * @static
275      * @return void
276      */
277     public static function bootstrap_moodle_info() {
278         global $CFG;
280         // All developers have to understand English, do not localise!
282         $release = null;
283         require("$CFG->dirroot/version.php");
285         echo "Moodle $release, $CFG->dbtype";
286         if ($hash = self::get_git_hash()) {
287             echo ", $hash";
288         }
289         echo "\n";
290     }
292     /**
293      * Try to get current git hash of the Moodle in $CFG->dirroot.
294      * @return string null if unknown, sha1 hash if known
295      */
296     public static function get_git_hash() {
297         global $CFG;
299         // This is a bit naive, but it should mostly work for all platforms.
301         if (!file_exists("$CFG->dirroot/.git/HEAD")) {
302             return null;
303         }
305         $ref = file_get_contents("$CFG->dirroot/.git/HEAD");
306         if ($ref === false) {
307             return null;
308         }
310         $ref = trim($ref);
312         if (strpos($ref, 'ref: ') !== 0) {
313             return null;
314         }
316         $ref = substr($ref, 5);
318         if (!file_exists("$CFG->dirroot/.git/$ref")) {
319             return null;
320         }
322         $hash = file_get_contents("$CFG->dirroot/.git/$ref");
324         if ($hash === false) {
325             return null;
326         }
328         $hash = trim($hash);
330         if (strlen($hash) != 40) {
331             return null;
332         }
334         return $hash;
335     }
337     /**
338      * Returns original state of global variable.
339      * @static
340      * @param string $name
341      * @return mixed
342      */
343     public static function get_global_backup($name) {
344         if ($name === 'DB') {
345             // no cloning of database object,
346             // we just need the original reference, not original state
347             return self::$globals['DB'];
348         }
349         if (isset(self::$globals[$name])) {
350             if (is_object(self::$globals[$name])) {
351                 $return = clone(self::$globals[$name]);
352                 return $return;
353             } else {
354                 return self::$globals[$name];
355             }
356         }
357         return null;
358     }
360     /**
361      * Is this site initialised to run unit tests?
362      *
363      * @static
364      * @return int array errorcode=>message, 0 means ok
365      */
366     public static function testing_ready_problem() {
367         global $DB;
369         if (!self::is_test_site()) {
370             // dataroot was verified in bootstrap, so it must be DB
371             return array(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not use database for testing, try different prefix');
372         }
374         $tables = $DB->get_tables(false);
375         if (empty($tables)) {
376             return array(PHPUNIT_EXITCODE_INSTALL, '');
377         }
379         if (!self::is_test_data_updated()) {
380             return array(PHPUNIT_EXITCODE_REINSTALL, '');
381         }
383         return array(0, '');
384     }
386     /**
387      * Drop all test site data.
388      *
389      * Note: To be used from CLI scripts only.
390      *
391      * @static
392      * @param bool $displayprogress if true, this method will echo progress information.
393      * @return void may terminate execution with exit code
394      */
395     public static function drop_site($displayprogress = false) {
396         global $DB, $CFG;
398         if (!self::is_test_site()) {
399             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not drop non-test site!!');
400         }
402         // Purge dataroot
403         if ($displayprogress) {
404             echo "Purging dataroot:\n";
405         }
407         self::reset_dataroot();
408         testing_initdataroot($CFG->dataroot, 'phpunit');
409         self::drop_dataroot();
411         // drop all tables
412         self::drop_database($displayprogress);
413     }
415     /**
416      * Perform a fresh test site installation
417      *
418      * Note: To be used from CLI scripts only.
419      *
420      * @static
421      * @return void may terminate execution with exit code
422      */
423     public static function install_site() {
424         global $DB, $CFG;
426         if (!self::is_test_site()) {
427             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not install on non-test site!!');
428         }
430         if ($DB->get_tables()) {
431             list($errorcode, $message) = phpunit_util::testing_ready_problem();
432             if ($errorcode) {
433                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_REINSTALL, 'Database tables already present, Moodle PHPUnit test environment can not be initialised');
434             } else {
435                 phpunit_bootstrap_error(0, 'Moodle PHPUnit test environment is already initialised');
436             }
437         }
439         $options = array();
440         $options['adminpass'] = 'admin';
441         $options['shortname'] = 'phpunit';
442         $options['fullname'] = 'PHPUnit test site';
444         install_cli_database($options, false);
446         // install timezone info
447         $timezones = get_records_csv($CFG->libdir.'/timezone.txt', 'timezone');
448         update_timezone_records($timezones);
450         // Store version hash in the database and in a file.
451         self::store_versions_hash();
453         // Store database data and structure.
454         self::store_database_state();
455     }
457     /**
458      * Builds dirroot/phpunit.xml and dataroot/phpunit/webrunner.xml files using defaults from /phpunit.xml.dist
459      * @static
460      * @return bool true means main config file created, false means only dataroot file created
461      */
462     public static function build_config_file() {
463         global $CFG;
465         $template = '
466         <testsuite name="@component@ test suite">
467             <directory suffix="_test.php">@dir@</directory>
468         </testsuite>';
469         $data = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
471         $suites = '';
473         $plugintypes = core_component::get_plugin_types();
474         ksort($plugintypes);
475         foreach ($plugintypes as $type=>$unused) {
476             $plugs = core_component::get_plugin_list($type);
477             ksort($plugs);
478             foreach ($plugs as $plug=>$fullplug) {
479                 if (!file_exists("$fullplug/tests/")) {
480                     continue;
481                 }
482                 $dir = substr($fullplug, strlen($CFG->dirroot)+1);
483                 $dir .= '/tests';
484                 $component = $type.'_'.$plug;
486                 $suite = str_replace('@component@', $component, $template);
487                 $suite = str_replace('@dir@', $dir, $suite);
489                 $suites .= $suite;
490             }
491         }
493         $data = preg_replace('|<!--@plugin_suites_start@-->.*<!--@plugin_suites_end@-->|s', $suites, $data, 1);
495         $result = false;
496         if (is_writable($CFG->dirroot)) {
497             if ($result = file_put_contents("$CFG->dirroot/phpunit.xml", $data)) {
498                 testing_fix_file_permissions("$CFG->dirroot/phpunit.xml");
499             }
500         }
502         // relink - it seems that xml:base does not work in phpunit xml files, remove this nasty hack if you find a way to set xml base for relative refs
503         $data = str_replace('lib/phpunit/', $CFG->dirroot.DIRECTORY_SEPARATOR.'lib'.DIRECTORY_SEPARATOR.'phpunit'.DIRECTORY_SEPARATOR, $data);
504         $data = preg_replace('|<directory suffix="_test.php">([^<]+)</directory>|',
505             '<directory suffix="_test.php">'.$CFG->dirroot.(DIRECTORY_SEPARATOR === '\\' ? '\\\\' : DIRECTORY_SEPARATOR).'$1</directory>',
506             $data);
507         file_put_contents("$CFG->dataroot/phpunit/webrunner.xml", $data);
508         testing_fix_file_permissions("$CFG->dataroot/phpunit/webrunner.xml");
510         return (bool)$result;
511     }
513     /**
514      * Builds phpunit.xml files for all components using defaults from /phpunit.xml.dist
515      *
516      * @static
517      * @return void, stops if can not write files
518      */
519     public static function build_component_config_files() {
520         global $CFG;
522         $template = '
523         <testsuites>
524             <testsuite name="@component@">
525                 <directory suffix="_test.php">.</directory>
526             </testsuite>
527         </testsuites>';
529         // Use the upstream file as source for the distributed configurations
530         $ftemplate = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
531         $ftemplate = preg_replace('|<!--All core suites.*</testsuites>|s', '<!--@component_suite@-->', $ftemplate);
533         // Gets all the components with tests
534         $components = tests_finder::get_components_with_tests('phpunit');
536         // Create the corresponding phpunit.xml file for each component
537         foreach ($components as $cname => $cpath) {
538             // Calculate the component suite
539             $ctemplate = $template;
540             $ctemplate = str_replace('@component@', $cname, $ctemplate);
542             // Apply it to the file template
543             $fcontents = str_replace('<!--@component_suite@-->', $ctemplate, $ftemplate);
545             // fix link to schema
546             $level = substr_count(str_replace('\\', '/', $cpath), '/') - substr_count(str_replace('\\', '/', $CFG->dirroot), '/');
547             $fcontents = str_replace('lib/phpunit/', str_repeat('../', $level).'lib/phpunit/', $fcontents);
549             // Write the file
550             $result = false;
551             if (is_writable($cpath)) {
552                 if ($result = (bool)file_put_contents("$cpath/phpunit.xml", $fcontents)) {
553                     testing_fix_file_permissions("$cpath/phpunit.xml");
554                 }
555             }
556             // Problems writing file, throw error
557             if (!$result) {
558                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGWARNING, "Can not create $cpath/phpunit.xml configuration file, verify dir permissions");
559             }
560         }
561     }
563     /**
564      * To be called from debugging() only.
565      * @param string $message
566      * @param int $level
567      * @param string $from
568      */
569     public static function debugging_triggered($message, $level, $from) {
570         // Store only if debugging triggered from actual test,
571         // we need normal debugging outside of tests to find problems in our phpunit integration.
572         $backtrace = debug_backtrace();
574         foreach ($backtrace as $bt) {
575             $intest = false;
576             if (isset($bt['object']) and is_object($bt['object'])) {
577                 if ($bt['object'] instanceof PHPUnit_Framework_TestCase) {
578                     if (strpos($bt['function'], 'test') === 0) {
579                         $intest = true;
580                         break;
581                     }
582                 }
583             }
584         }
585         if (!$intest) {
586             return false;
587         }
589         $debug = new stdClass();
590         $debug->message = $message;
591         $debug->level   = $level;
592         $debug->from    = $from;
594         self::$debuggings[] = $debug;
596         return true;
597     }
599     /**
600      * Resets the list of debugging messages.
601      */
602     public static function reset_debugging() {
603         self::$debuggings = array();
604         set_debugging(DEBUG_DEVELOPER);
605     }
607     /**
608      * Returns all debugging messages triggered during test.
609      * @return array with instances having message, level and stacktrace property.
610      */
611     public static function get_debugging_messages() {
612         return self::$debuggings;
613     }
615     /**
616      * Prints out any debug messages accumulated during test execution.
617      * @return bool false if no debug messages, true if debug triggered
618      */
619     public static function display_debugging_messages() {
620         if (empty(self::$debuggings)) {
621             return false;
622         }
623         foreach(self::$debuggings as $debug) {
624             echo 'Debugging: ' . $debug->message . "\n" . trim($debug->from) . "\n";
625         }
627         return true;
628     }
630     /**
631      * Start message redirection.
632      *
633      * Note: Do not call directly from tests,
634      *       use $sink = $this->redirectMessages() instead.
635      *
636      * @return phpunit_message_sink
637      */
638     public static function start_message_redirection() {
639         if (self::$messagesink) {
640             self::stop_message_redirection();
641         }
642         self::$messagesink = new phpunit_message_sink();
643         return self::$messagesink;
644     }
646     /**
647      * End message redirection.
648      *
649      * Note: Do not call directly from tests,
650      *       use $sink->close() instead.
651      */
652     public static function stop_message_redirection() {
653         self::$messagesink = null;
654     }
656     /**
657      * Are messages redirected to some sink?
658      *
659      * Note: to be called from messagelib.php only!
660      *
661      * @return bool
662      */
663     public static function is_redirecting_messages() {
664         return !empty(self::$messagesink);
665     }
667     /**
668      * To be called from messagelib.php only!
669      *
670      * @param stdClass $message record from message_read table
671      * @return bool true means send message, false means message "sent" to sink.
672      */
673     public static function message_sent($message) {
674         if (self::$messagesink) {
675             self::$messagesink->add_message($message);
676         }
677     }
679     /**
680      * Start phpmailer redirection.
681      *
682      * Note: Do not call directly from tests,
683      *       use $sink = $this->redirectEmails() instead.
684      *
685      * @return phpunit_phpmailer_sink
686      */
687     public static function start_phpmailer_redirection() {
688         if (self::$phpmailersink) {
689             self::stop_phpmailer_redirection();
690         }
691         self::$phpmailersink = new phpunit_phpmailer_sink();
692         return self::$phpmailersink;
693     }
695     /**
696      * End phpmailer redirection.
697      *
698      * Note: Do not call directly from tests,
699      *       use $sink->close() instead.
700      */
701     public static function stop_phpmailer_redirection() {
702         self::$phpmailersink = null;
703     }
705     /**
706      * Are messages for phpmailer redirected to some sink?
707      *
708      * Note: to be called from moodle_phpmailer.php only!
709      *
710      * @return bool
711      */
712     public static function is_redirecting_phpmailer() {
713         return !empty(self::$phpmailersink);
714     }
716     /**
717      * To be called from messagelib.php only!
718      *
719      * @param stdClass $message record from message_read table
720      * @return bool true means send message, false means message "sent" to sink.
721      */
722     public static function phpmailer_sent($message) {
723         if (self::$phpmailersink) {
724             self::$phpmailersink->add_message($message);
725         }
726     }
728     /**
729      * Start event redirection.
730      *
731      * @private
732      * Note: Do not call directly from tests,
733      *       use $sink = $this->redirectEvents() instead.
734      *
735      * @return phpunit_event_sink
736      */
737     public static function start_event_redirection() {
738         if (self::$eventsink) {
739             self::stop_event_redirection();
740         }
741         self::$eventsink = new phpunit_event_sink();
742         return self::$eventsink;
743     }
745     /**
746      * End event redirection.
747      *
748      * @private
749      * Note: Do not call directly from tests,
750      *       use $sink->close() instead.
751      */
752     public static function stop_event_redirection() {
753         self::$eventsink = null;
754     }
756     /**
757      * Are events redirected to some sink?
758      *
759      * Note: to be called from \core\event\base only!
760      *
761      * @private
762      * @return bool
763      */
764     public static function is_redirecting_events() {
765         return !empty(self::$eventsink);
766     }
768     /**
769      * To be called from \core\event\base only!
770      *
771      * @private
772      * @param \core\event\base $event record from event_read table
773      * @return bool true means send event, false means event "sent" to sink.
774      */
775     public static function event_triggered(\core\event\base $event) {
776         if (self::$eventsink) {
777             self::$eventsink->add_event($event);
778         }
779     }