MDL-37458 testing common methods generalization
[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     /**
47      * @var array Files to skip when resetting dataroot folder
48      */
49     protected static $datarootskiponreset = array('.', '..', 'phpunittestdir.txt', 'phpunit', '.htaccess');
51     /**
52      * @var array Files to skip when dropping dataroot folder
53      */
54     protected static $datarootskipondrop = array('.', '..', 'lock', 'webrunner.xml');
56     /**
57      * Load global $CFG;
58      * @internal
59      * @static
60      * @return void
61      */
62     public static function initialise_cfg() {
63         global $DB;
64         $dbhash = false;
65         try {
66             $dbhash = $DB->get_field('config', 'value', array('name'=>'phpunittest'));
67         } catch (Exception $e) {
68             // not installed yet
69             initialise_cfg();
70             return;
71         }
72         if ($dbhash !== self::get_version_hash()) {
73             // do not set CFG - the only way forward is to drop and reinstall
74             return;
75         }
76         // standard CFG init
77         initialise_cfg();
78     }
80     /**
81      * Reset contents of all database tables to initial values, reset caches, etc.
82      *
83      * Note: this is relatively slow (cca 2 seconds for pg and 7 for mysql) - please use with care!
84      *
85      * @static
86      * @param bool $logchanges log changes in global state and database in error log
87      * @return void
88      */
89     public static function reset_all_data($logchanges = false) {
90         global $DB, $CFG, $USER, $SITE, $COURSE, $PAGE, $OUTPUT, $SESSION, $GROUPLIB_CACHE;
92         // Stop any message redirection.
93         phpunit_util::stop_message_redirection();
95         // Release memory and indirectly call destroy() methods to release resource handles, etc.
96         gc_collect_cycles();
98         // Show any unhandled debugging messages, the runbare() could already reset it.
99         self::display_debugging_messages();
100         self::reset_debugging();
102         // reset global $DB in case somebody mocked it
103         $DB = self::get_global_backup('DB');
105         if ($DB->is_transaction_started()) {
106             // we can not reset inside transaction
107             $DB->force_transaction_rollback();
108         }
110         $resetdb = self::reset_database();
111         $warnings = array();
113         if ($logchanges) {
114             if ($resetdb) {
115                 $warnings[] = 'Warning: unexpected database modification, resetting DB state';
116             }
118             $oldcfg = self::get_global_backup('CFG');
119             $oldsite = self::get_global_backup('SITE');
120             foreach($CFG as $k=>$v) {
121                 if (!property_exists($oldcfg, $k)) {
122                     $warnings[] = 'Warning: unexpected new $CFG->'.$k.' value';
123                 } else if ($oldcfg->$k !== $CFG->$k) {
124                     $warnings[] = 'Warning: unexpected change of $CFG->'.$k.' value';
125                 }
126                 unset($oldcfg->$k);
128             }
129             if ($oldcfg) {
130                 foreach($oldcfg as $k=>$v) {
131                     $warnings[] = 'Warning: unexpected removal of $CFG->'.$k;
132                 }
133             }
135             if ($USER->id != 0) {
136                 $warnings[] = 'Warning: unexpected change of $USER';
137             }
139             if ($COURSE->id != $oldsite->id) {
140                 $warnings[] = 'Warning: unexpected change of $COURSE';
141             }
142         }
144         // restore original globals
145         $_SERVER = self::get_global_backup('_SERVER');
146         $CFG = self::get_global_backup('CFG');
147         $SITE = self::get_global_backup('SITE');
148         $COURSE = $SITE;
150         // reinitialise following globals
151         $OUTPUT = new bootstrap_renderer();
152         $PAGE = new moodle_page();
153         $FULLME = null;
154         $ME = null;
155         $SCRIPT = null;
156         $SESSION = new stdClass();
157         $_SESSION['SESSION'] =& $SESSION;
159         // set fresh new not-logged-in user
160         $user = new stdClass();
161         $user->id = 0;
162         $user->mnethostid = $CFG->mnet_localhost_id;
163         session_set_user($user);
165         // reset all static caches
166         accesslib_clear_all_caches(true);
167         get_string_manager()->reset_caches(true);
168         reset_text_filters_cache(true);
169         events_get_handlers('reset');
170         textlib::reset_caches();
171         if (class_exists('repository')) {
172             repository::reset_caches();
173         }
174         $GROUPLIB_CACHE = null;
175         //TODO MDL-25290: add more resets here and probably refactor them to new core function
177         // Reset course and module caches.
178         if (class_exists('format_base')) {
179             // If file containing class is not loaded, there is no cache there anyway.
180             format_base::reset_course_cache(0);
181         }
182         get_fast_modinfo(0, 0, true);
184         // Reset other singletons.
185         if (class_exists('plugin_manager')) {
186             plugin_manager::reset_caches(true);
187         }
188         if (class_exists('available_update_checker')) {
189             available_update_checker::reset_caches(true);
190         }
191         if (class_exists('available_update_deployer')) {
192             available_update_deployer::reset_caches(true);
193         }
195         // purge dataroot directory
196         self::reset_dataroot();
198         // restore original config once more in case resetting of caches changed CFG
199         $CFG = self::get_global_backup('CFG');
201         // inform data generator
202         self::get_data_generator()->reset();
204         // fix PHP settings
205         error_reporting($CFG->debug);
207         // verify db writes just in case something goes wrong in reset
208         if (self::$lastdbwrites != $DB->perf_get_writes()) {
209             error_log('Unexpected DB writes in phpunit_util::reset_all_data()');
210             self::$lastdbwrites = $DB->perf_get_writes();
211         }
213         if ($warnings) {
214             $warnings = implode("\n", $warnings);
215             trigger_error($warnings, E_USER_WARNING);
216         }
217     }
219     /**
220      * Called during bootstrap only!
221      * @internal
222      * @static
223      * @return void
224      */
225     public static function bootstrap_init() {
226         global $CFG, $SITE, $DB;
228         // backup the globals
229         self::$globals['_SERVER'] = $_SERVER;
230         self::$globals['CFG'] = clone($CFG);
231         self::$globals['SITE'] = clone($SITE);
232         self::$globals['DB'] = $DB;
234         // refresh data in all tables, clear caches, etc.
235         phpunit_util::reset_all_data();
236     }
238     /**
239      * Returns original state of global variable.
240      * @static
241      * @param string $name
242      * @return mixed
243      */
244     public static function get_global_backup($name) {
245         if ($name === 'DB') {
246             // no cloning of database object,
247             // we just need the original reference, not original state
248             return self::$globals['DB'];
249         }
250         if (isset(self::$globals[$name])) {
251             if (is_object(self::$globals[$name])) {
252                 $return = clone(self::$globals[$name]);
253                 return $return;
254             } else {
255                 return self::$globals[$name];
256             }
257         }
258         return null;
259     }
261     /**
262      * Is this site initialised to run unit tests?
263      *
264      * @static
265      * @return int array errorcode=>message, 0 means ok
266      */
267     public static function testing_ready_problem() {
268         global $DB;
270         if (!self::is_test_site()) {
271             // dataroot was verified in bootstrap, so it must be DB
272             return array(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not use database for testing, try different prefix');
273         }
275         $tables = $DB->get_tables(false);
276         if (empty($tables)) {
277             return array(PHPUNIT_EXITCODE_INSTALL, '');
278         }
280         if (!self::is_test_data_updated()) {
281             return array(PHPUNIT_EXITCODE_REINSTALL, '');
282         }
284         return array(0, '');
285     }
287     /**
288      * Drop all test site data.
289      *
290      * Note: To be used from CLI scripts only.
291      *
292      * @static
293      * @param bool $displayprogress if true, this method will echo progress information.
294      * @return void may terminate execution with exit code
295      */
296     public static function drop_site($displayprogress = false) {
297         global $DB, $CFG;
299         if (!self::is_test_site()) {
300             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not drop non-test site!!');
301         }
303         // Purge dataroot
304         if ($displayprogress) {
305             echo "Purging dataroot:\n";
306         }
308         self::reset_dataroot();
309         testing_initdataroot($CFG->dataroot, 'phpunit');
310         self::drop_dataroot();
312         // drop all tables
313         self::drop_database($displayprogress);
314     }
316     /**
317      * Perform a fresh test site installation
318      *
319      * Note: To be used from CLI scripts only.
320      *
321      * @static
322      * @return void may terminate execution with exit code
323      */
324     public static function install_site() {
325         global $DB, $CFG;
327         if (!self::is_test_site()) {
328             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not install on non-test site!!');
329         }
331         if ($DB->get_tables()) {
332             list($errorcode, $message) = phpunit_util::testing_ready_problem();
333             if ($errorcode) {
334                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_REINSTALL, 'Database tables already present, Moodle PHPUnit test environment can not be initialised');
335             } else {
336                 phpunit_bootstrap_error(0, 'Moodle PHPUnit test environment is already initialised');
337             }
338         }
340         $options = array();
341         $options['adminpass'] = 'admin';
342         $options['shortname'] = 'phpunit';
343         $options['fullname'] = 'PHPUnit test site';
345         install_cli_database($options, false);
347         // install timezone info
348         $timezones = get_records_csv($CFG->libdir.'/timezone.txt', 'timezone');
349         update_timezone_records($timezones);
351         // Store version hash in the database and in a file.
352         self::store_versions_hash();
354         // Store database data and structure.
355         self::store_database_state();
356     }
358     /**
359      * Builds dirroot/phpunit.xml and dataroot/phpunit/webrunner.xml files using defaults from /phpunit.xml.dist
360      * @static
361      * @return bool true means main config file created, false means only dataroot file created
362      */
363     public static function build_config_file() {
364         global $CFG;
366         $template = '
367         <testsuite name="@component@ test suite">
368             <directory suffix="_test.php">@dir@</directory>
369         </testsuite>';
370         $data = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
372         $suites = '';
374         $plugintypes = get_plugin_types();
375         ksort($plugintypes);
376         foreach ($plugintypes as $type=>$unused) {
377             $plugs = get_plugin_list($type);
378             ksort($plugs);
379             foreach ($plugs as $plug=>$fullplug) {
380                 if (!file_exists("$fullplug/tests/")) {
381                     continue;
382                 }
383                 $dir = substr($fullplug, strlen($CFG->dirroot)+1);
384                 $dir .= '/tests';
385                 $component = $type.'_'.$plug;
387                 $suite = str_replace('@component@', $component, $template);
388                 $suite = str_replace('@dir@', $dir, $suite);
390                 $suites .= $suite;
391             }
392         }
394         $data = preg_replace('|<!--@plugin_suites_start@-->.*<!--@plugin_suites_end@-->|s', $suites, $data, 1);
396         $result = false;
397         if (is_writable($CFG->dirroot)) {
398             if ($result = file_put_contents("$CFG->dirroot/phpunit.xml", $data)) {
399                 testing_fix_file_permissions("$CFG->dirroot/phpunit.xml");
400             }
401         }
403         // 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
404         $data = str_replace('lib/phpunit/', $CFG->dirroot.DIRECTORY_SEPARATOR.'lib'.DIRECTORY_SEPARATOR.'phpunit'.DIRECTORY_SEPARATOR, $data);
405         $data = preg_replace('|<directory suffix="_test.php">([^<]+)</directory>|',
406             '<directory suffix="_test.php">'.$CFG->dirroot.(DIRECTORY_SEPARATOR === '\\' ? '\\\\' : DIRECTORY_SEPARATOR).'$1</directory>',
407             $data);
408         file_put_contents("$CFG->dataroot/phpunit/webrunner.xml", $data);
409         testing_fix_file_permissions("$CFG->dataroot/phpunit/webrunner.xml");
411         return (bool)$result;
412     }
414     /**
415      * Builds phpunit.xml files for all components using defaults from /phpunit.xml.dist
416      *
417      * @static
418      * @return void, stops if can not write files
419      */
420     public static function build_component_config_files() {
421         global $CFG;
423         $template = '
424         <testsuites>
425             <testsuite name="@component@">
426                 <directory suffix="_test.php">.</directory>
427             </testsuite>
428         </testsuites>';
430         // Use the upstream file as source for the distributed configurations
431         $ftemplate = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
432         $ftemplate = preg_replace('|<!--All core suites.*</testsuites>|s', '<!--@component_suite@-->', $ftemplate);
434         // Gets all the components with tests
435         $components = tests_finder::get_components_with_tests('phpunit');
437         // Create the corresponding phpunit.xml file for each component
438         foreach ($components as $cname => $cpath) {
439             // Calculate the component suite
440             $ctemplate = $template;
441             $ctemplate = str_replace('@component@', $cname, $ctemplate);
443             // Apply it to the file template
444             $fcontents = str_replace('<!--@component_suite@-->', $ctemplate, $ftemplate);
446             // fix link to schema
447             $level = substr_count(str_replace('\\', '/', $cpath), '/') - substr_count(str_replace('\\', '/', $CFG->dirroot), '/');
448             $fcontents = str_replace('lib/phpunit/', str_repeat('../', $level).'lib/phpunit/', $fcontents);
450             // Write the file
451             $result = false;
452             if (is_writable($cpath)) {
453                 if ($result = (bool)file_put_contents("$cpath/phpunit.xml", $fcontents)) {
454                     testing_fix_file_permissions("$cpath/phpunit.xml");
455                 }
456             }
457             // Problems writing file, throw error
458             if (!$result) {
459                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGWARNING, "Can not create $cpath/phpunit.xml configuration file, verify dir permissions");
460             }
461         }
462     }
464     /**
465      * To be called from debugging() only.
466      * @param string $message
467      * @param int $level
468      * @param string $from
469      */
470     public static function debugging_triggered($message, $level, $from) {
471         // Store only if debugging triggered from actual test,
472         // we need normal debugging outside of tests to find problems in our phpunit integration.
473         $backtrace = debug_backtrace();
475         foreach ($backtrace as $bt) {
476             $intest = false;
477             if (isset($bt['object']) and is_object($bt['object'])) {
478                 if ($bt['object'] instanceof PHPUnit_Framework_TestCase) {
479                     if (strpos($bt['function'], 'test') === 0) {
480                         $intest = true;
481                         break;
482                     }
483                 }
484             }
485         }
486         if (!$intest) {
487             return false;
488         }
490         $debug = new stdClass();
491         $debug->message = $message;
492         $debug->level   = $level;
493         $debug->from    = $from;
495         self::$debuggings[] = $debug;
497         return true;
498     }
500     /**
501      * Resets the list of debugging messages.
502      */
503     public static function reset_debugging() {
504         self::$debuggings = array();
505     }
507     /**
508      * Returns all debugging messages triggered during test.
509      * @return array with instances having message, level and stacktrace property.
510      */
511     public static function get_debugging_messages() {
512         return self::$debuggings;
513     }
515     /**
516      * Prints out any debug messages accumulated during test execution.
517      * @return bool false if no debug messages, true if debug triggered
518      */
519     public static function display_debugging_messages() {
520         if (empty(self::$debuggings)) {
521             return false;
522         }
523         foreach(self::$debuggings as $debug) {
524             echo 'Debugging: ' . $debug->message . "\n" . trim($debug->from) . "\n";
525         }
527         return true;
528     }
530     /**
531      * Start message redirection.
532      *
533      * Note: Do not call directly from tests,
534      *       use $sink = $this->redirectMessages() instead.
535      *
536      * @return phpunit_message_sink
537      */
538     public static function start_message_redirection() {
539         if (self::$messagesink) {
540             self::stop_message_redirection();
541         }
542         self::$messagesink = new phpunit_message_sink();
543         return self::$messagesink;
544     }
546     /**
547      * End message redirection.
548      *
549      * Note: Do not call directly from tests,
550      *       use $sink->close() instead.
551      */
552     public static function stop_message_redirection() {
553         self::$messagesink = null;
554     }
556     /**
557      * Are messages redirected to some sink?
558      *
559      * Note: to be called from messagelib.php only!
560      *
561      * @return bool
562      */
563     public static function is_redirecting_messages() {
564         return !empty(self::$messagesink);
565     }
567     /**
568      * To be called from messagelib.php only!
569      *
570      * @param stdClass $message record from message_read table
571      * @return bool true means send message, false means message "sent" to sink.
572      */
573     public static function message_sent($message) {
574         if (self::$messagesink) {
575             self::$messagesink->add_message($message);
576         }
577     }