MDL-68098 tests: Reset FILTERLIB_PRIVATE after tests
[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');
27 require_once(__DIR__ . "/coverage_info.php");
29 /**
30  * Collection of utility methods.
31  *
32  * @package    core
33  * @category   phpunit
34  * @copyright  2012 Petr Skoda {@link http://skodak.org}
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 class phpunit_util extends testing_util {
38     /**
39      * @var int last value of db writes counter, used for db resetting
40      */
41     public static $lastdbwrites = null;
43     /** @var array An array of original globals, restored after each test */
44     protected static $globals = array();
46     /** @var array list of debugging messages triggered during the last test execution */
47     protected static $debuggings = array();
49     /** @var phpunit_message_sink alternative target for moodle messaging */
50     protected static $messagesink = null;
52     /** @var phpunit_phpmailer_sink alternative target for phpmailer messaging */
53     protected static $phpmailersink = null;
55     /** @var phpunit_message_sink alternative target for moodle messaging */
56     protected static $eventsink = null;
58     /**
59      * @var array Files to skip when resetting dataroot folder
60      */
61     protected static $datarootskiponreset = array('.', '..', 'phpunittestdir.txt', 'phpunit', '.htaccess');
63     /**
64      * @var array Files to skip when dropping dataroot folder
65      */
66     protected static $datarootskipondrop = array('.', '..', 'lock');
68     /**
69      * Load global $CFG;
70      * @internal
71      * @static
72      * @return void
73      */
74     public static function initialise_cfg() {
75         global $DB;
76         $dbhash = false;
77         try {
78             $dbhash = $DB->get_field('config', 'value', array('name'=>'phpunittest'));
79         } catch (Exception $e) {
80             // not installed yet
81             initialise_cfg();
82             return;
83         }
84         if ($dbhash !== core_component::get_all_versions_hash()) {
85             // do not set CFG - the only way forward is to drop and reinstall
86             return;
87         }
88         // standard CFG init
89         initialise_cfg();
90     }
92     /**
93      * Reset contents of all database tables to initial values, reset caches, etc.
94      *
95      * Note: this is relatively slow (cca 2 seconds for pg and 7 for mysql) - please use with care!
96      *
97      * @static
98      * @param bool $detectchanges
99      *      true  - changes in global state and database are reported as errors
100      *      false - no errors reported
101      *      null  - only critical problems are reported as errors
102      * @return void
103      */
104     public static function reset_all_data($detectchanges = false) {
105         global $DB, $CFG, $USER, $SITE, $COURSE, $PAGE, $OUTPUT, $SESSION, $FULLME, $FILTERLIB_PRIVATE;
107         // Stop any message redirection.
108         self::stop_message_redirection();
110         // Stop any message redirection.
111         self::stop_event_redirection();
113         // Start a new email redirection.
114         // This will clear any existing phpmailer redirection.
115         // We redirect all phpmailer output to this message sink which is
116         // called instead of phpmailer actually sending the message.
117         self::start_phpmailer_redirection();
119         // We used to call gc_collect_cycles here to ensure desctructors were called between tests.
120         // This accounted for 25% of the total time running phpunit - so we removed it.
122         // Show any unhandled debugging messages, the runbare() could already reset it.
123         self::display_debugging_messages();
124         self::reset_debugging();
126         // reset global $DB in case somebody mocked it
127         $DB = self::get_global_backup('DB');
129         if ($DB->is_transaction_started()) {
130             // we can not reset inside transaction
131             $DB->force_transaction_rollback();
132         }
134         $resetdb = self::reset_database();
135         $localename = self::get_locale_name();
136         $warnings = array();
138         if ($detectchanges === true) {
139             if ($resetdb) {
140                 $warnings[] = 'Warning: unexpected database modification, resetting DB state';
141             }
143             $oldcfg = self::get_global_backup('CFG');
144             $oldsite = self::get_global_backup('SITE');
145             foreach($CFG as $k=>$v) {
146                 if (!property_exists($oldcfg, $k)) {
147                     $warnings[] = 'Warning: unexpected new $CFG->'.$k.' value';
148                 } else if ($oldcfg->$k !== $CFG->$k) {
149                     $warnings[] = 'Warning: unexpected change of $CFG->'.$k.' value';
150                 }
151                 unset($oldcfg->$k);
153             }
154             if ($oldcfg) {
155                 foreach($oldcfg as $k=>$v) {
156                     $warnings[] = 'Warning: unexpected removal of $CFG->'.$k;
157                 }
158             }
160             if ($USER->id != 0) {
161                 $warnings[] = 'Warning: unexpected change of $USER';
162             }
164             if ($COURSE->id != $oldsite->id) {
165                 $warnings[] = 'Warning: unexpected change of $COURSE';
166             }
168             if ($FULLME !== self::get_global_backup('FULLME')) {
169                 $warnings[] = 'Warning: unexpected change of $FULLME';
170             }
172             if (setlocale(LC_TIME, 0) !== $localename) {
173                 $warnings[] = 'Warning: unexpected change of locale';
174             }
175         }
177         if (ini_get('max_execution_time') != 0) {
178             // This is special warning for all resets because we do not want any
179             // libraries to mess with timeouts unintentionally.
180             // Our PHPUnit integration is not supposed to change it either.
182             if ($detectchanges !== false) {
183                 $warnings[] = 'Warning: max_execution_time was changed to '.ini_get('max_execution_time');
184             }
185             set_time_limit(0);
186         }
188         // restore original globals
189         $_SERVER = self::get_global_backup('_SERVER');
190         $CFG = self::get_global_backup('CFG');
191         $SITE = self::get_global_backup('SITE');
192         $FULLME = self::get_global_backup('FULLME');
193         $_GET = array();
194         $_POST = array();
195         $_FILES = array();
196         $_REQUEST = array();
197         $COURSE = $SITE;
199         // reinitialise following globals
200         $OUTPUT = new bootstrap_renderer();
201         $PAGE = new moodle_page();
202         $FULLME = null;
203         $ME = null;
204         $SCRIPT = null;
205         $FILTERLIB_PRIVATE = null;
207         // Empty sessison and set fresh new not-logged-in user.
208         \core\session\manager::init_empty_session();
210         // reset all static caches
211         \core\event\manager::phpunit_reset();
212         accesslib_clear_all_caches(true);
213         accesslib_reset_role_cache();
214         get_string_manager()->reset_caches(true);
215         reset_text_filters_cache(true);
216         core_text::reset_caches();
217         get_message_processors(false, true, true);
218         filter_manager::reset_caches();
219         core_filetypes::reset_caches();
220         \core_search\manager::clear_static();
221         core_user::reset_caches();
222         \core\output\icon_system::reset_caches();
223         if (class_exists('core_media_manager', false)) {
224             core_media_manager::reset_caches();
225         }
227         // Reset static unit test options.
228         if (class_exists('\availability_date\condition', false)) {
229             \availability_date\condition::set_current_time_for_test(0);
230         }
232         // Reset internal users.
233         core_user::reset_internal_users();
235         // Clear static caches in calendar container.
236         if (class_exists('\core_calendar\local\event\container', false)) {
237             core_calendar\local\event\container::reset_caches();
238         }
240         //TODO MDL-25290: add more resets here and probably refactor them to new core function
242         // Reset course and module caches.
243         if (class_exists('format_base')) {
244             // If file containing class is not loaded, there is no cache there anyway.
245             format_base::reset_course_cache(0);
246         }
247         get_fast_modinfo(0, 0, true);
249         // Reset other singletons.
250         if (class_exists('core_plugin_manager')) {
251             core_plugin_manager::reset_caches(true);
252         }
253         if (class_exists('\core\update\checker')) {
254             \core\update\checker::reset_caches(true);
255         }
256         if (class_exists('\core_course\customfield\course_handler')) {
257             \core_course\customfield\course_handler::reset_caches();
258         }
260         // Clear static cache within restore.
261         if (class_exists('restore_section_structure_step')) {
262             restore_section_structure_step::reset_caches();
263         }
265         // purge dataroot directory
266         self::reset_dataroot();
268         // restore original config once more in case resetting of caches changed CFG
269         $CFG = self::get_global_backup('CFG');
271         // inform data generator
272         self::get_data_generator()->reset();
274         // fix PHP settings
275         error_reporting($CFG->debug);
277         // Reset the date/time class.
278         core_date::phpunit_reset();
280         // Make sure the time locale is consistent - that is Australian English.
281         setlocale(LC_TIME, $localename);
283         // Reset the log manager cache.
284         get_log_manager(true);
286         // Reset user agent.
287         core_useragent::instance(true, null);
289         // verify db writes just in case something goes wrong in reset
290         if (self::$lastdbwrites != $DB->perf_get_writes()) {
291             error_log('Unexpected DB writes in phpunit_util::reset_all_data()');
292             self::$lastdbwrites = $DB->perf_get_writes();
293         }
295         if ($warnings) {
296             $warnings = implode("\n", $warnings);
297             trigger_error($warnings, E_USER_WARNING);
298         }
299     }
301     /**
302      * Reset all database tables to default values.
303      * @static
304      * @return bool true if reset done, false if skipped
305      */
306     public static function reset_database() {
307         global $DB;
309         if (!is_null(self::$lastdbwrites) and self::$lastdbwrites == $DB->perf_get_writes()) {
310             return false;
311         }
313         if (!parent::reset_database()) {
314             return false;
315         }
317         self::$lastdbwrites = $DB->perf_get_writes();
319         return true;
320     }
322     /**
323      * Called during bootstrap only!
324      * @internal
325      * @static
326      * @return void
327      */
328     public static function bootstrap_init() {
329         global $CFG, $SITE, $DB, $FULLME;
331         // backup the globals
332         self::$globals['_SERVER'] = $_SERVER;
333         self::$globals['CFG'] = clone($CFG);
334         self::$globals['SITE'] = clone($SITE);
335         self::$globals['DB'] = $DB;
336         self::$globals['FULLME'] = $FULLME;
338         // refresh data in all tables, clear caches, etc.
339         self::reset_all_data();
340     }
342     /**
343      * Print some Moodle related info to console.
344      * @internal
345      * @static
346      * @return void
347      */
348     public static function bootstrap_moodle_info() {
349         echo self::get_site_info();
350     }
352     /**
353      * Returns original state of global variable.
354      * @static
355      * @param string $name
356      * @return mixed
357      */
358     public static function get_global_backup($name) {
359         if ($name === 'DB') {
360             // no cloning of database object,
361             // we just need the original reference, not original state
362             return self::$globals['DB'];
363         }
364         if (isset(self::$globals[$name])) {
365             if (is_object(self::$globals[$name])) {
366                 $return = clone(self::$globals[$name]);
367                 return $return;
368             } else {
369                 return self::$globals[$name];
370             }
371         }
372         return null;
373     }
375     /**
376      * Is this site initialised to run unit tests?
377      *
378      * @static
379      * @return int array errorcode=>message, 0 means ok
380      */
381     public static function testing_ready_problem() {
382         global $DB;
384         $localename = self::get_locale_name();
385         if (setlocale(LC_TIME, $localename) === false) {
386             return array(PHPUNIT_EXITCODE_CONFIGERROR, "Required locale '$localename' is not installed.");
387         }
389         if (!self::is_test_site()) {
390             // dataroot was verified in bootstrap, so it must be DB
391             return array(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not use database for testing, try different prefix');
392         }
394         $tables = $DB->get_tables(false);
395         if (empty($tables)) {
396             return array(PHPUNIT_EXITCODE_INSTALL, '');
397         }
399         if (!self::is_test_data_updated()) {
400             return array(PHPUNIT_EXITCODE_REINSTALL, '');
401         }
403         return array(0, '');
404     }
406     /**
407      * Drop all test site data.
408      *
409      * Note: To be used from CLI scripts only.
410      *
411      * @static
412      * @param bool $displayprogress if true, this method will echo progress information.
413      * @return void may terminate execution with exit code
414      */
415     public static function drop_site($displayprogress = false) {
416         global $DB, $CFG;
418         if (!self::is_test_site()) {
419             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not drop non-test site!!');
420         }
422         // Purge dataroot
423         if ($displayprogress) {
424             echo "Purging dataroot:\n";
425         }
427         self::reset_dataroot();
428         testing_initdataroot($CFG->dataroot, 'phpunit');
430         // Drop all tables.
431         self::drop_database($displayprogress);
433         // Drop dataroot.
434         self::drop_dataroot();
435     }
437     /**
438      * Perform a fresh test site installation
439      *
440      * Note: To be used from CLI scripts only.
441      *
442      * @static
443      * @return void may terminate execution with exit code
444      */
445     public static function install_site() {
446         global $DB, $CFG;
448         if (!self::is_test_site()) {
449             phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR, 'Can not install on non-test site!!');
450         }
452         if ($DB->get_tables()) {
453             list($errorcode, $message) = self::testing_ready_problem();
454             if ($errorcode) {
455                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_REINSTALL, 'Database tables already present, Moodle PHPUnit test environment can not be initialised');
456             } else {
457                 phpunit_bootstrap_error(0, 'Moodle PHPUnit test environment is already initialised');
458             }
459         }
461         $options = array();
462         $options['adminpass'] = 'admin';
463         $options['shortname'] = 'phpunit';
464         $options['fullname'] = 'PHPUnit test site';
466         install_cli_database($options, false);
468         // Set the admin email address.
469         $DB->set_field('user', 'email', 'admin@example.com', array('username' => 'admin'));
471         // Disable all logging for performance and sanity reasons.
472         set_config('enabled_stores', '', 'tool_log');
474         // We need to keep the installed dataroot filedir files.
475         // So each time we reset the dataroot before running a test, the default files are still installed.
476         self::save_original_data_files();
478         // Store version hash in the database and in a file.
479         self::store_versions_hash();
481         // Store database data and structure.
482         self::store_database_state();
483     }
485     /**
486      * Builds dirroot/phpunit.xml file using defaults from /phpunit.xml.dist
487      * @static
488      * @return bool true means main config file created, false means only dataroot file created
489      */
490     public static function build_config_file() {
491         global $CFG;
493         $template = '
494         <testsuite name="@component@_testsuite">
495             <directory suffix="_test.php">@dir@</directory>
496         </testsuite>';
497         $filtertemplate = '
498         <testsuite name="@component@_testsuite">
499             <directory suffix="_test.php">@dir@</directory>
500         </testsuite>';
501         $data = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
503         $suites = '';
504         $whitelists = [];
505         $excludelists = [];
507         $subsystems = core_component::get_core_subsystems();
508         $subsystems['core'] = $CFG->dirroot . '/lib';
509         foreach ($subsystems as $subsystem => $fulldir) {
510             if (empty($fulldir)) {
511                 continue;
512             }
513             if (!file_exists("{$fulldir}/tests/")) {
514                 // There are no tests - skip this directory.
515                 continue;
516             }
518             $dir = substr($fulldir, strlen($CFG->dirroot) + 1);
519             if ($coverageinfo = self::get_coverage_info($fulldir)) {
520                 $whitelists = array_merge($whitelists, $coverageinfo->get_whitelists($dir));
521                 $excludelists = array_merge($excludelists, $coverageinfo->get_excludelists($dir));
522             }
523         }
525         $plugintypes = core_component::get_plugin_types();
526         ksort($plugintypes);
527         foreach (array_keys($plugintypes) as $type) {
528             $plugs = core_component::get_plugin_list($type);
529             ksort($plugs);
530             foreach ($plugs as $plug => $plugindir) {
531                 if (!file_exists("{$plugindir}/tests/")) {
532                     // There are no tests - skip this directory.
533                     continue;
534                 }
536                 $dir = substr($plugindir, strlen($CFG->dirroot) + 1);
537                 $testdir = "{$dir}/tests";
538                 $component = "{$type}_{$plug}";
540                 $suite = str_replace('@component@', $component, $template);
541                 $suite = str_replace('@dir@', $testdir, $suite);
543                 $suites .= $suite;
545                 if ($coverageinfo = self::get_coverage_info($plugindir)) {
547                     $whitelists = array_merge($whitelists, $coverageinfo->get_whitelists($dir));
548                     $excludelists = array_merge($excludelists, $coverageinfo->get_excludelists($dir));
549                 }
550             }
551         }
553         // Start a sequence between 100000 and 199000 to ensure each call to init produces
554         // different ids in the database.  This reduces the risk that hard coded values will
555         // end up being placed in phpunit or behat test code.
556         $sequencestart = 100000 + mt_rand(0, 99) * 1000;
558         $data = preg_replace('|<!--@plugin_suites_start@-->.*<!--@plugin_suites_end@-->|s', $suites, $data, 1);
559         $data = str_replace(
560             '<const name="PHPUNIT_SEQUENCE_START" value=""/>',
561             '<const name="PHPUNIT_SEQUENCE_START" value="' . $sequencestart . '"/>',
562             $data);
564         $filters = self::get_filter_config($whitelists, $excludelists);
565         $data = str_replace('<!--@filterlist@-->', $filters, $data);
567         $result = false;
568         if (is_writable($CFG->dirroot)) {
569             if ($result = file_put_contents("$CFG->dirroot/phpunit.xml", $data)) {
570                 testing_fix_file_permissions("$CFG->dirroot/phpunit.xml");
571             }
572         }
574         return (bool)$result;
575     }
577     /**
578      * Builds phpunit.xml files for all components using defaults from /phpunit.xml.dist
579      *
580      * @static
581      * @return void, stops if can not write files
582      */
583     public static function build_component_config_files() {
584         global $CFG;
586         $template = '
587     <testsuites>
588         <testsuite name="@component@_testsuite">
589             <directory suffix="_test.php">.</directory>
590         </testsuite>
591     </testsuites>';
592         $filterdefault = '
593             <whitelist processUncoveredFilesFromWhitelist="false">
594                 <directory suffix=".php">.</directory>
595                 <exclude>
596                     <directory suffix="_test.php">.</directory>
597                 </exclude>
598             </whitelist>';
600         // Start a sequence between 100000 and 199000 to ensure each call to init produces
601         // different ids in the database.  This reduces the risk that hard coded values will
602         // end up being placed in phpunit or behat test code.
603         $sequencestart = 100000 + mt_rand(0, 99) * 1000;
605         // Use the upstream file as source for the distributed configurations
606         $ftemplate = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
607         $ftemplate = preg_replace('|<!--All core suites.*</testsuites>|s', '<!--@component_suite@-->', $ftemplate);
609         // Gets all the components with tests
610         $components = tests_finder::get_components_with_tests('phpunit');
612         // Create the corresponding phpunit.xml file for each component
613         foreach ($components as $cname => $cpath) {
614             // Calculate the component suite
615             $ctemplate = $template;
616             $ctemplate = str_replace('@component@', $cname, $ctemplate);
618             $fcontents = str_replace('<!--@component_suite@-->', $ctemplate, $ftemplate);
620             // Check for filter configurations.
621             if ($coverageinfo = self::get_coverage_info($cpath)) {
622                 $filters = self::get_filter_config($coverageinfo->get_whitelists(''), $coverageinfo->get_excludelists(''));
623             } else {
624                 $filters = $filterdefault;
625             }
626             $fcontents = str_replace('<!--@filterlist@-->', $filters, $fcontents);
628             // Apply it to the file template.
629             $fcontents = str_replace(
630                 '<const name="PHPUNIT_SEQUENCE_START" value=""/>',
631                 '<const name="PHPUNIT_SEQUENCE_START" value="' . $sequencestart . '"/>',
632                 $fcontents);
634             // fix link to schema
635             $level = substr_count(str_replace('\\', '/', $cpath), '/') - substr_count(str_replace('\\', '/', $CFG->dirroot), '/');
636             $fcontents = str_replace('lib/phpunit/', str_repeat('../', $level).'lib/phpunit/', $fcontents);
638             // Write the file
639             $result = false;
640             if (is_writable($cpath)) {
641                 if ($result = (bool)file_put_contents("$cpath/phpunit.xml", $fcontents)) {
642                     testing_fix_file_permissions("$cpath/phpunit.xml");
643                 }
644             }
645             // Problems writing file, throw error
646             if (!$result) {
647                 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGWARNING, "Can not create $cpath/phpunit.xml configuration file, verify dir permissions");
648             }
649         }
650     }
652     /**
653      * To be called from debugging() only.
654      * @param string $message
655      * @param int $level
656      * @param string $from
657      */
658     public static function debugging_triggered($message, $level, $from) {
659         // Store only if debugging triggered from actual test,
660         // we need normal debugging outside of tests to find problems in our phpunit integration.
661         $backtrace = debug_backtrace();
663         foreach ($backtrace as $bt) {
664             if (isset($bt['object']) and is_object($bt['object'])
665                     && $bt['object'] instanceof PHPUnit\Framework\TestCase) {
666                 $debug = new stdClass();
667                 $debug->message = $message;
668                 $debug->level   = $level;
669                 $debug->from    = $from;
671                 self::$debuggings[] = $debug;
673                 return true;
674             }
675         }
676         return false;
677     }
679     /**
680      * Resets the list of debugging messages.
681      */
682     public static function reset_debugging() {
683         self::$debuggings = array();
684         set_debugging(DEBUG_DEVELOPER);
685     }
687     /**
688      * Returns all debugging messages triggered during test.
689      * @return array with instances having message, level and stacktrace property.
690      */
691     public static function get_debugging_messages() {
692         return self::$debuggings;
693     }
695     /**
696      * Prints out any debug messages accumulated during test execution.
697      *
698      * @param bool $return true to return the messages or false to print them directly. Default false.
699      * @return bool|string false if no debug messages, true if debug triggered or string of messages
700      */
701     public static function display_debugging_messages($return = false) {
702         if (empty(self::$debuggings)) {
703             return false;
704         }
706         $debugstring = '';
707         foreach(self::$debuggings as $debug) {
708             $debugstring .= 'Debugging: ' . $debug->message . "\n" . trim($debug->from) . "\n";
709         }
711         if ($return) {
712             return $debugstring;
713         }
714         echo $debugstring;
715         return true;
716     }
718     /**
719      * Start message redirection.
720      *
721      * Note: Do not call directly from tests,
722      *       use $sink = $this->redirectMessages() instead.
723      *
724      * @return phpunit_message_sink
725      */
726     public static function start_message_redirection() {
727         if (self::$messagesink) {
728             self::stop_message_redirection();
729         }
730         self::$messagesink = new phpunit_message_sink();
731         return self::$messagesink;
732     }
734     /**
735      * End message redirection.
736      *
737      * Note: Do not call directly from tests,
738      *       use $sink->close() instead.
739      */
740     public static function stop_message_redirection() {
741         self::$messagesink = null;
742     }
744     /**
745      * Are messages redirected to some sink?
746      *
747      * Note: to be called from messagelib.php only!
748      *
749      * @return bool
750      */
751     public static function is_redirecting_messages() {
752         return !empty(self::$messagesink);
753     }
755     /**
756      * To be called from messagelib.php only!
757      *
758      * @param stdClass $message record from messages table
759      * @return bool true means send message, false means message "sent" to sink.
760      */
761     public static function message_sent($message) {
762         if (self::$messagesink) {
763             self::$messagesink->add_message($message);
764         }
765     }
767     /**
768      * Start phpmailer redirection.
769      *
770      * Note: Do not call directly from tests,
771      *       use $sink = $this->redirectEmails() instead.
772      *
773      * @return phpunit_phpmailer_sink
774      */
775     public static function start_phpmailer_redirection() {
776         if (self::$phpmailersink) {
777             // If an existing mailer sink is active, just clear it.
778             self::$phpmailersink->clear();
779         } else {
780             self::$phpmailersink = new phpunit_phpmailer_sink();
781         }
782         return self::$phpmailersink;
783     }
785     /**
786      * End phpmailer redirection.
787      *
788      * Note: Do not call directly from tests,
789      *       use $sink->close() instead.
790      */
791     public static function stop_phpmailer_redirection() {
792         self::$phpmailersink = null;
793     }
795     /**
796      * Are messages for phpmailer redirected to some sink?
797      *
798      * Note: to be called from moodle_phpmailer.php only!
799      *
800      * @return bool
801      */
802     public static function is_redirecting_phpmailer() {
803         return !empty(self::$phpmailersink);
804     }
806     /**
807      * To be called from messagelib.php only!
808      *
809      * @param stdClass $message record from messages table
810      * @return bool true means send message, false means message "sent" to sink.
811      */
812     public static function phpmailer_sent($message) {
813         if (self::$phpmailersink) {
814             self::$phpmailersink->add_message($message);
815         }
816     }
818     /**
819      * Start event redirection.
820      *
821      * @private
822      * Note: Do not call directly from tests,
823      *       use $sink = $this->redirectEvents() instead.
824      *
825      * @return phpunit_event_sink
826      */
827     public static function start_event_redirection() {
828         if (self::$eventsink) {
829             self::stop_event_redirection();
830         }
831         self::$eventsink = new phpunit_event_sink();
832         return self::$eventsink;
833     }
835     /**
836      * End event redirection.
837      *
838      * @private
839      * Note: Do not call directly from tests,
840      *       use $sink->close() instead.
841      */
842     public static function stop_event_redirection() {
843         self::$eventsink = null;
844     }
846     /**
847      * Are events redirected to some sink?
848      *
849      * Note: to be called from \core\event\base only!
850      *
851      * @private
852      * @return bool
853      */
854     public static function is_redirecting_events() {
855         return !empty(self::$eventsink);
856     }
858     /**
859      * To be called from \core\event\base only!
860      *
861      * @private
862      * @param \core\event\base $event record from event_read table
863      * @return bool true means send event, false means event "sent" to sink.
864      */
865     public static function event_triggered(\core\event\base $event) {
866         if (self::$eventsink) {
867             self::$eventsink->add_event($event);
868         }
869     }
871     /**
872      * Gets the name of the locale for testing environment (Australian English)
873      * depending on platform environment.
874      *
875      * @return string the locale name.
876      */
877     protected static function get_locale_name() {
878         global $CFG;
879         if ($CFG->ostype === 'WINDOWS') {
880             return 'English_Australia.1252';
881         } else {
882             return 'en_AU.UTF-8';
883         }
884     }
886     /**
887      * Executes all adhoc tasks in the queue. Useful for testing asynchronous behaviour.
888      *
889      * @return void
890      */
891     public static function run_all_adhoc_tasks() {
892         $now = time();
893         while (($task = \core\task\manager::get_next_adhoc_task($now)) !== null) {
894             try {
895                 $task->execute();
896                 \core\task\manager::adhoc_task_complete($task);
897             } catch (Exception $e) {
898                 \core\task\manager::adhoc_task_failed($task);
899             }
900         }
901     }
903     /**
904      * Helper function to call a protected/private method of an object using reflection.
905      *
906      * Example 1. Calling a protected object method:
907      *   $result = call_internal_method($myobject, 'method_name', [$param1, $param2], '\my\namespace\myobjectclassname');
908      *
909      * Example 2. Calling a protected static method:
910      *   $result = call_internal_method(null, 'method_name', [$param1, $param2], '\my\namespace\myclassname');
911      *
912      * @param object|null $object the object on which to call the method, or null if calling a static method.
913      * @param string $methodname the name of the protected/private method.
914      * @param array $params the array of function params to pass to the method.
915      * @param string $classname the fully namespaced name of the class the object was created from (base in the case of mocks),
916      *        or the name of the static class when calling a static method.
917      * @return mixed the respective return value of the method.
918      */
919     public static function call_internal_method($object, $methodname, array $params = array(), $classname) {
920         $reflection = new \ReflectionClass($classname);
921         $method = $reflection->getMethod($methodname);
922         $method->setAccessible(true);
923         return $method->invokeArgs($object, $params);
924     }
926     /**
927      * Pad the supplied string with $level levels of indentation.
928      *
929      * @param   string  $string The string to pad
930      * @param   int     $level The number of levels of indentation to pad
931      * @return  string
932      */
933     protected static function pad(string $string, int $level) : string {
934         return str_repeat(" ", $level * 4) . "{$string}\n";
935     }
937     /**
938      * Get the filter config for the supplied whitelist and excludelist configuration.
939      *
940      * @param   array[] $whitelists The list of files/folders in the whitelist.
941      * @param   array[] $excludelists The list of files/folders in the excludelist.
942      * @return  string
943      */
944     protected static function get_filter_config(array $whitelists, array $excludelists) : string {
945         $filters = '';
946         if (!empty($whitelists)) {
947             $filters .= self::pad("<whitelist>", 2);
948             foreach ($whitelists as $line) {
949                 $filters .= self::pad($line, 3);
950             }
951             if (!empty($excludelists)) {
952                 $filters .= self::pad("<exclude>", 3);
953                 foreach ($excludelists as $line) {
954                     $filters .= self::pad($line, 4);
955                 }
956                 $filters .= self::pad("</exclude>", 3);
957             }
958             $filters .= self::pad("</whitelist>", 2);
959         }
961         return $filters;
962     }
964     /**
965      * Get the phpunit_coverage_info for the specified plugin or subsystem directory.
966      *
967      * @param   string  $fulldir The directory to find the coverage info file in.
968      * @return  phpunit_coverage_info
969      */
970     protected static function get_coverage_info(string $fulldir): ?phpunit_coverage_info {
971         $coverageconfig = "{$fulldir}/tests/coverage.php";
972         if (file_exists($coverageconfig)) {
973             $coverageinfo = require($coverageconfig);
974             if (!$coverageinfo instanceof phpunit_coverage_info) {
975                 throw new \coding_exception("{$coverageconfig} does not return a phpunit_coverage_info");
976             }
978             return $coverageinfo;
979         }
981         return null;
982     }
984     /**
985      * Whether the current process is an isolated test process.
986      *
987      * @return bool
988      */
989     public static function is_in_isolated_process(): bool {
990         // Note: There is no function to call, or much to go by in order to tell whether we are in an isolated process
991         // during Bootstrap, when this function is called.
992         // We can do so by testing the existence of the wrapper function, but there is nothing set until that point.
993         return function_exists('__phpunit_run_isolated_test');
994     }