2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
22 * @copyright 2012 Petr Skoda {@link http://skodak.org}
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 require_once(__DIR__
.'/../../testing/classes/util.php');
29 * Collection of utility methods.
33 * @copyright 2012 Petr Skoda {@link http://skodak.org}
34 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 class phpunit_util
extends testing_util
{
38 * @var int last value of db writes counter, used for db resetting
40 public static $lastdbwrites = null;
42 /** @var array An array of original globals, restored after each test */
43 protected static $globals = array();
45 /** @var array list of debugging messages triggered during the last test execution */
46 protected static $debuggings = array();
48 /** @var phpunit_message_sink alternative target for moodle messaging */
49 protected static $messagesink = null;
51 /** @var phpunit_phpmailer_sink alternative target for phpmailer messaging */
52 protected static $phpmailersink = null;
54 /** @var phpunit_message_sink alternative target for moodle messaging */
55 protected static $eventsink = null;
58 * @var array Files to skip when resetting dataroot folder
60 protected static $datarootskiponreset = array('.', '..', 'phpunittestdir.txt', 'phpunit', '.htaccess');
63 * @var array Files to skip when dropping dataroot folder
65 protected static $datarootskipondrop = array('.', '..', 'lock', 'webrunner.xml');
73 public static function initialise_cfg() {
77 $dbhash = $DB->get_field('config', 'value', array('name'=>'phpunittest'));
78 } catch (Exception
$e) {
83 if ($dbhash !== core_component
::get_all_versions_hash()) {
84 // do not set CFG - the only way forward is to drop and reinstall
92 * Reset contents of all database tables to initial values, reset caches, etc.
94 * Note: this is relatively slow (cca 2 seconds for pg and 7 for mysql) - please use with care!
97 * @param bool $detectchanges
98 * true - changes in global state and database are reported as errors
99 * false - no errors reported
100 * null - only critical problems are reported as errors
103 public static function reset_all_data($detectchanges = false) {
104 global $DB, $CFG, $USER, $SITE, $COURSE, $PAGE, $OUTPUT, $SESSION;
106 // Stop any message redirection.
107 phpunit_util
::stop_message_redirection();
109 // Stop any message redirection.
110 phpunit_util
::stop_event_redirection();
112 // Start a new email redirection.
113 // This will clear any existing phpmailer redirection.
114 // We redirect all phpmailer output to this message sink which is
115 // called instead of phpmailer actually sending the message.
116 phpunit_util
::start_phpmailer_redirection();
118 // We used to call gc_collect_cycles here to ensure desctructors were called between tests.
119 // This accounted for 25% of the total time running phpunit - so we removed it.
121 // Show any unhandled debugging messages, the runbare() could already reset it.
122 self
::display_debugging_messages();
123 self
::reset_debugging();
125 // reset global $DB in case somebody mocked it
126 $DB = self
::get_global_backup('DB');
128 if ($DB->is_transaction_started()) {
129 // we can not reset inside transaction
130 $DB->force_transaction_rollback();
133 $resetdb = self
::reset_database();
136 if ($detectchanges === true) {
138 $warnings[] = 'Warning: unexpected database modification, resetting DB state';
141 $oldcfg = self
::get_global_backup('CFG');
142 $oldsite = self
::get_global_backup('SITE');
143 foreach($CFG as $k=>$v) {
144 if (!property_exists($oldcfg, $k)) {
145 $warnings[] = 'Warning: unexpected new $CFG->'.$k.' value';
146 } else if ($oldcfg->$k !== $CFG->$k) {
147 $warnings[] = 'Warning: unexpected change of $CFG->'.$k.' value';
153 foreach($oldcfg as $k=>$v) {
154 $warnings[] = 'Warning: unexpected removal of $CFG->'.$k;
158 if ($USER->id
!= 0) {
159 $warnings[] = 'Warning: unexpected change of $USER';
162 if ($COURSE->id
!= $oldsite->id
) {
163 $warnings[] = 'Warning: unexpected change of $COURSE';
166 if ($CFG->ostype
=== 'WINDOWS') {
167 if (setlocale(LC_TIME
, 0) !== 'English_Australia.1252') {
168 $warnings[] = 'Warning: unexpected change of locale';
171 if (setlocale(LC_TIME
, 0) !== 'en_AU.UTF-8') {
172 $warnings[] = 'Warning: unexpected change of locale';
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');
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');
198 // reinitialise following globals
199 $OUTPUT = new bootstrap_renderer();
200 $PAGE = new moodle_page();
205 // Empty sessison and set fresh new not-logged-in user.
206 \core\session\manager
::init_empty_session();
208 // reset all static caches
209 \core\event\manager
::phpunit_reset();
210 accesslib_clear_all_caches(true);
211 get_string_manager()->reset_caches(true);
212 reset_text_filters_cache(true);
213 events_get_handlers('reset');
214 core_text
::reset_caches();
215 get_message_processors(false, true);
216 filter_manager
::reset_caches();
217 core_filetypes
::reset_caches();
219 // Reset static unit test options.
220 if (class_exists('\availability_date\condition', false)) {
221 \availability_date\condition
::set_current_time_for_test(0);
224 // Reset internal users.
225 core_user
::reset_internal_users();
227 //TODO MDL-25290: add more resets here and probably refactor them to new core function
229 // Reset course and module caches.
230 if (class_exists('format_base')) {
231 // If file containing class is not loaded, there is no cache there anyway.
232 format_base
::reset_course_cache(0);
234 get_fast_modinfo(0, 0, true);
236 // Reset other singletons.
237 if (class_exists('core_plugin_manager')) {
238 core_plugin_manager
::reset_caches(true);
240 if (class_exists('\core\update\checker')) {
241 \core\update\checker
::reset_caches(true);
243 if (class_exists('\core\update\deployer')) {
244 \core\update\deployer
::reset_caches(true);
247 // Clear static cache within restore.
248 if (class_exists('restore_section_structure_step')) {
249 restore_section_structure_step
::reset_caches();
252 // purge dataroot directory
253 self
::reset_dataroot();
255 // restore original config once more in case resetting of caches changed CFG
256 $CFG = self
::get_global_backup('CFG');
258 // inform data generator
259 self
::get_data_generator()->reset();
262 error_reporting($CFG->debug
);
264 // Reset the date/time class.
265 core_date
::phpunit_reset();
267 // Make sure the time locale is consistent - that is Australian English.
268 if ($CFG->ostype
=== 'WINDOWS') {
269 setlocale(LC_TIME
, 'English_Australia.1252');
271 setlocale(LC_TIME
, 'en_AU.UTF-8');
274 // verify db writes just in case something goes wrong in reset
275 if (self
::$lastdbwrites != $DB->perf_get_writes()) {
276 error_log('Unexpected DB writes in phpunit_util::reset_all_data()');
277 self
::$lastdbwrites = $DB->perf_get_writes();
281 $warnings = implode("\n", $warnings);
282 trigger_error($warnings, E_USER_WARNING
);
287 * Reset all database tables to default values.
289 * @return bool true if reset done, false if skipped
291 public static function reset_database() {
294 if (!is_null(self
::$lastdbwrites) and self
::$lastdbwrites == $DB->perf_get_writes()) {
298 if (!parent
::reset_database()) {
302 self
::$lastdbwrites = $DB->perf_get_writes();
308 * Called during bootstrap only!
313 public static function bootstrap_init() {
314 global $CFG, $SITE, $DB;
316 // backup the globals
317 self
::$globals['_SERVER'] = $_SERVER;
318 self
::$globals['CFG'] = clone($CFG);
319 self
::$globals['SITE'] = clone($SITE);
320 self
::$globals['DB'] = $DB;
322 // refresh data in all tables, clear caches, etc.
323 phpunit_util
::reset_all_data();
327 * Print some Moodle related info to console.
332 public static function bootstrap_moodle_info() {
333 echo self
::get_site_info();
337 * Returns original state of global variable.
339 * @param string $name
342 public static function get_global_backup($name) {
343 if ($name === 'DB') {
344 // no cloning of database object,
345 // we just need the original reference, not original state
346 return self
::$globals['DB'];
348 if (isset(self
::$globals[$name])) {
349 if (is_object(self
::$globals[$name])) {
350 $return = clone(self
::$globals[$name]);
353 return self
::$globals[$name];
360 * Is this site initialised to run unit tests?
363 * @return int array errorcode=>message, 0 means ok
365 public static function testing_ready_problem() {
368 if (!self
::is_test_site()) {
369 // dataroot was verified in bootstrap, so it must be DB
370 return array(PHPUNIT_EXITCODE_CONFIGERROR
, 'Can not use database for testing, try different prefix');
373 $tables = $DB->get_tables(false);
374 if (empty($tables)) {
375 return array(PHPUNIT_EXITCODE_INSTALL
, '');
378 if (!self
::is_test_data_updated()) {
379 return array(PHPUNIT_EXITCODE_REINSTALL
, '');
386 * Drop all test site data.
388 * Note: To be used from CLI scripts only.
391 * @param bool $displayprogress if true, this method will echo progress information.
392 * @return void may terminate execution with exit code
394 public static function drop_site($displayprogress = false) {
397 if (!self
::is_test_site()) {
398 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR
, 'Can not drop non-test site!!');
402 if ($displayprogress) {
403 echo "Purging dataroot:\n";
406 self
::reset_dataroot();
407 testing_initdataroot($CFG->dataroot
, 'phpunit');
408 self
::drop_dataroot();
411 self
::drop_database($displayprogress);
415 * Perform a fresh test site installation
417 * Note: To be used from CLI scripts only.
420 * @return void may terminate execution with exit code
422 public static function install_site() {
425 if (!self
::is_test_site()) {
426 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGERROR
, 'Can not install on non-test site!!');
429 if ($DB->get_tables()) {
430 list($errorcode, $message) = phpunit_util
::testing_ready_problem();
432 phpunit_bootstrap_error(PHPUNIT_EXITCODE_REINSTALL
, 'Database tables already present, Moodle PHPUnit test environment can not be initialised');
434 phpunit_bootstrap_error(0, 'Moodle PHPUnit test environment is already initialised');
439 $options['adminpass'] = 'admin';
440 $options['shortname'] = 'phpunit';
441 $options['fullname'] = 'PHPUnit test site';
443 install_cli_database($options, false);
445 // Set the admin email address.
446 $DB->set_field('user', 'email', 'admin@example.com', array('username' => 'admin'));
448 // Disable all logging for performance and sanity reasons.
449 set_config('enabled_stores', '', 'tool_log');
451 // We need to keep the installed dataroot filedir files.
452 // So each time we reset the dataroot before running a test, the default files are still installed.
453 self
::save_original_data_files();
455 // Store version hash in the database and in a file.
456 self
::store_versions_hash();
458 // Store database data and structure.
459 self
::store_database_state();
463 * Builds dirroot/phpunit.xml and dataroot/phpunit/webrunner.xml files using defaults from /phpunit.xml.dist
465 * @return bool true means main config file created, false means only dataroot file created
467 public static function build_config_file() {
471 <testsuite name="@component@_testsuite">
472 <directory suffix="_test.php">@dir@</directory>
474 $data = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
478 $plugintypes = core_component
::get_plugin_types();
480 foreach ($plugintypes as $type=>$unused) {
481 $plugs = core_component
::get_plugin_list($type);
483 foreach ($plugs as $plug=>$fullplug) {
484 if (!file_exists("$fullplug/tests/")) {
487 $dir = substr($fullplug, strlen($CFG->dirroot
)+
1);
489 $component = $type.'_'.$plug;
491 $suite = str_replace('@component@', $component, $template);
492 $suite = str_replace('@dir@', $dir, $suite);
497 // Start a sequence between 100000 and 199000 to ensure each call to init produces
498 // different ids in the database. This reduces the risk that hard coded values will
499 // end up being placed in phpunit or behat test code.
500 $sequencestart = 100000 +
mt_rand(0, 99) * 1000;
502 $data = preg_replace('|<!--@plugin_suites_start@-->.*<!--@plugin_suites_end@-->|s', $suites, $data, 1);
504 '<const name="PHPUNIT_SEQUENCE_START" value=""/>',
505 '<const name="PHPUNIT_SEQUENCE_START" value="' . $sequencestart . '"/>',
509 if (is_writable($CFG->dirroot
)) {
510 if ($result = file_put_contents("$CFG->dirroot/phpunit.xml", $data)) {
511 testing_fix_file_permissions("$CFG->dirroot/phpunit.xml");
515 // 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
516 $data = str_replace('lib/phpunit/', $CFG->dirroot
.DIRECTORY_SEPARATOR
.'lib'.DIRECTORY_SEPARATOR
.'phpunit'.DIRECTORY_SEPARATOR
, $data);
517 $data = preg_replace('|<directory suffix="_test.php">([^<]+)</directory>|',
518 '<directory suffix="_test.php">'.$CFG->dirroot
.(DIRECTORY_SEPARATOR
=== '\\' ?
'\\\\' : DIRECTORY_SEPARATOR
).'$1</directory>',
520 file_put_contents("$CFG->dataroot/phpunit/webrunner.xml", $data);
521 testing_fix_file_permissions("$CFG->dataroot/phpunit/webrunner.xml");
523 return (bool)$result;
527 * Builds phpunit.xml files for all components using defaults from /phpunit.xml.dist
530 * @return void, stops if can not write files
532 public static function build_component_config_files() {
537 <testsuite name="@component@_testsuite">
538 <directory suffix="_test.php">.</directory>
542 // Start a sequence between 100000 and 199000 to ensure each call to init produces
543 // different ids in the database. This reduces the risk that hard coded values will
544 // end up being placed in phpunit or behat test code.
545 $sequencestart = 100000 +
mt_rand(0, 99) * 1000;
547 // Use the upstream file as source for the distributed configurations
548 $ftemplate = file_get_contents("$CFG->dirroot/phpunit.xml.dist");
549 $ftemplate = preg_replace('|<!--All core suites.*</testsuites>|s', '<!--@component_suite@-->', $ftemplate);
551 // Gets all the components with tests
552 $components = tests_finder
::get_components_with_tests('phpunit');
554 // Create the corresponding phpunit.xml file for each component
555 foreach ($components as $cname => $cpath) {
556 // Calculate the component suite
557 $ctemplate = $template;
558 $ctemplate = str_replace('@component@', $cname, $ctemplate);
560 // Apply it to the file template
561 $fcontents = str_replace('<!--@component_suite@-->', $ctemplate, $ftemplate);
562 $fcontents = str_replace(
563 '<const name="PHPUNIT_SEQUENCE_START" value=""/>',
564 '<const name="PHPUNIT_SEQUENCE_START" value="' . $sequencestart . '"/>',
567 // fix link to schema
568 $level = substr_count(str_replace('\\', '/', $cpath), '/') - substr_count(str_replace('\\', '/', $CFG->dirroot
), '/');
569 $fcontents = str_replace('lib/phpunit/', str_repeat('../', $level).'lib/phpunit/', $fcontents);
573 if (is_writable($cpath)) {
574 if ($result = (bool)file_put_contents("$cpath/phpunit.xml", $fcontents)) {
575 testing_fix_file_permissions("$cpath/phpunit.xml");
578 // Problems writing file, throw error
580 phpunit_bootstrap_error(PHPUNIT_EXITCODE_CONFIGWARNING
, "Can not create $cpath/phpunit.xml configuration file, verify dir permissions");
586 * To be called from debugging() only.
587 * @param string $message
589 * @param string $from
591 public static function debugging_triggered($message, $level, $from) {
592 // Store only if debugging triggered from actual test,
593 // we need normal debugging outside of tests to find problems in our phpunit integration.
594 $backtrace = debug_backtrace();
596 foreach ($backtrace as $bt) {
598 if (isset($bt['object']) and is_object($bt['object'])) {
599 if ($bt['object'] instanceof PHPUnit_Framework_TestCase
) {
600 if (strpos($bt['function'], 'test') === 0) {
611 $debug = new stdClass();
612 $debug->message
= $message;
613 $debug->level
= $level;
614 $debug->from
= $from;
616 self
::$debuggings[] = $debug;
622 * Resets the list of debugging messages.
624 public static function reset_debugging() {
625 self
::$debuggings = array();
626 set_debugging(DEBUG_DEVELOPER
);
630 * Returns all debugging messages triggered during test.
631 * @return array with instances having message, level and stacktrace property.
633 public static function get_debugging_messages() {
634 return self
::$debuggings;
638 * Prints out any debug messages accumulated during test execution.
639 * @return bool false if no debug messages, true if debug triggered
641 public static function display_debugging_messages() {
642 if (empty(self
::$debuggings)) {
645 foreach(self
::$debuggings as $debug) {
646 echo 'Debugging: ' . $debug->message
. "\n" . trim($debug->from
) . "\n";
653 * Start message redirection.
655 * Note: Do not call directly from tests,
656 * use $sink = $this->redirectMessages() instead.
658 * @return phpunit_message_sink
660 public static function start_message_redirection() {
661 if (self
::$messagesink) {
662 self
::stop_message_redirection();
664 self
::$messagesink = new phpunit_message_sink();
665 return self
::$messagesink;
669 * End message redirection.
671 * Note: Do not call directly from tests,
672 * use $sink->close() instead.
674 public static function stop_message_redirection() {
675 self
::$messagesink = null;
679 * Are messages redirected to some sink?
681 * Note: to be called from messagelib.php only!
685 public static function is_redirecting_messages() {
686 return !empty(self
::$messagesink);
690 * To be called from messagelib.php only!
692 * @param stdClass $message record from message_read table
693 * @return bool true means send message, false means message "sent" to sink.
695 public static function message_sent($message) {
696 if (self
::$messagesink) {
697 self
::$messagesink->add_message($message);
702 * Start phpmailer redirection.
704 * Note: Do not call directly from tests,
705 * use $sink = $this->redirectEmails() instead.
707 * @return phpunit_phpmailer_sink
709 public static function start_phpmailer_redirection() {
710 if (self
::$phpmailersink) {
711 // If an existing mailer sink is active, just clear it.
712 self
::$phpmailersink->clear();
714 self
::$phpmailersink = new phpunit_phpmailer_sink();
716 return self
::$phpmailersink;
720 * End phpmailer redirection.
722 * Note: Do not call directly from tests,
723 * use $sink->close() instead.
725 public static function stop_phpmailer_redirection() {
726 self
::$phpmailersink = null;
730 * Are messages for phpmailer redirected to some sink?
732 * Note: to be called from moodle_phpmailer.php only!
736 public static function is_redirecting_phpmailer() {
737 return !empty(self
::$phpmailersink);
741 * To be called from messagelib.php only!
743 * @param stdClass $message record from message_read table
744 * @return bool true means send message, false means message "sent" to sink.
746 public static function phpmailer_sent($message) {
747 if (self
::$phpmailersink) {
748 self
::$phpmailersink->add_message($message);
753 * Start event redirection.
756 * Note: Do not call directly from tests,
757 * use $sink = $this->redirectEvents() instead.
759 * @return phpunit_event_sink
761 public static function start_event_redirection() {
762 if (self
::$eventsink) {
763 self
::stop_event_redirection();
765 self
::$eventsink = new phpunit_event_sink();
766 return self
::$eventsink;
770 * End event redirection.
773 * Note: Do not call directly from tests,
774 * use $sink->close() instead.
776 public static function stop_event_redirection() {
777 self
::$eventsink = null;
781 * Are events redirected to some sink?
783 * Note: to be called from \core\event\base only!
788 public static function is_redirecting_events() {
789 return !empty(self
::$eventsink);
793 * To be called from \core\event\base only!
796 * @param \core\event\base $event record from event_read table
797 * @return bool true means send event, false means event "sent" to sink.
799 public static function event_triggered(\core\event\base
$event) {
800 if (self
::$eventsink) {
801 self
::$eventsink->add_event($event);