Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Advanced test case.
 *
 * @package    core
 * @category   phpunit
 * @copyright  2012 Petr Skoda {@link http://skodak.org}
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */


/**
 * Advanced PHPUnit test case customised for Moodle.
 *
 * @package    core
 * @category   phpunit
 * @copyright  2012 Petr Skoda {@link http://skodak.org}
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class advanced_testcase extends base_testcase {
    /** @var bool automatically reset everything? null means log changes */
    private $resetAfterTest;

    /** @var moodle_transaction */
    private $testdbtransaction;

    /** @var int timestamp used for current time asserts */
    private $currenttimestart;

    /**
     * Constructs a test case with the given name.
     *
     * Note: use setUp() or setUpBeforeClass() in your test cases.
     *
     * @param string $name
     * @param array  $data
     * @param string $dataName
     */
    final public function __construct($name = null, array $data = array(), $dataName = '') {
        parent::__construct($name, $data, $dataName);

        $this->setBackupGlobals(false);
        $this->setBackupStaticAttributes(false);
        $this->setPreserveGlobalState(false);
    }

    /**
     * Runs the bare test sequence.
     * @return void
     */
    final public function runBare(): void {
        global $DB;

        if (phpunit_util::$lastdbwrites != $DB->perf_get_writes()) {
            // this happens when previous test does not reset, we can not use transactions
            $this->testdbtransaction = null;

        } else if ($DB->get_dbfamily() === 'postgres' or $DB->get_dbfamily() === 'mssql') {
            // database must allow rollback of DDL, so no mysql here
            $this->testdbtransaction = $DB->start_delegated_transaction();
        }

        try {
            $this->setCurrentTimeStart();
            parent::runBare();
            // set DB reference in case somebody mocked it in test
            $DB = phpunit_util::get_global_backup('DB');

            // Deal with any debugging messages.
            $debugerror = phpunit_util::display_debugging_messages(true);
            $this->resetDebugging();
            if (!empty($debugerror)) {
                trigger_error('Unexpected debugging() call detected.'."\n".$debugerror, E_USER_NOTICE);
            }

        } catch (Exception $ex) {
            $e = $ex;
        } catch (Throwable $ex) {
            // Engine errors in PHP7 throw exceptions of type Throwable (this "catch" will be ignored in PHP5).
            $e = $ex;
        }

        if (isset($e)) {
            // cleanup after failed expectation
            self::resetAllData();
            throw $e;
        }

        if (!$this->testdbtransaction or $this->testdbtransaction->is_disposed()) {
            $this->testdbtransaction = null;
        }

        if ($this->resetAfterTest === true) {
            if ($this->testdbtransaction) {
                $DB->force_transaction_rollback();
                phpunit_util::reset_all_database_sequences();
                phpunit_util::$lastdbwrites = $DB->perf_get_writes(); // no db reset necessary
            }
            self::resetAllData(null);

        } else if ($this->resetAfterTest === false) {
            if ($this->testdbtransaction) {
                $this->testdbtransaction->allow_commit();
            }
            // keep all data untouched for other tests

        } else {
            // reset but log what changed
            if ($this->testdbtransaction) {
                try {
                    $this->testdbtransaction->allow_commit();
                } catch (dml_transaction_exception $e) {
                    self::resetAllData();
                    throw new coding_exception('Invalid transaction state detected in test '.$this->getName());
                }
            }
            self::resetAllData(true);
        }

        // Reset context cache.
        context_helper::reset_caches();

        // make sure test did not forget to close transaction
        if ($DB->is_transaction_started()) {
            self::resetAllData();
            if ($this->getStatus() == PHPUnit\Runner\BaseTestRunner::STATUS_PASSED
                or $this->getStatus() == PHPUnit\Runner\BaseTestRunner::STATUS_SKIPPED
                or $this->getStatus() == PHPUnit\Runner\BaseTestRunner::STATUS_INCOMPLETE) {
                throw new coding_exception('Test '.$this->getName().' did not close database transaction');
            }
        }
    }

    /**
< * Creates a new FlatXmlDataSet with the given $xmlFile. (absolute path.) < * < * @param string $xmlFile < * @return PHPUnit\DbUnit\DataSet\FlatXmlDataSet < */ < protected function createFlatXMLDataSet($xmlFile) { < return new PHPUnit\DbUnit\DataSet\FlatXmlDataSet($xmlFile); < } < < /**
* Creates a new XMLDataSet with the given $xmlFile. (absolute path.) *
> * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info. * @param string $xmlFile > * @todo This will be removed for Moodle 4.2 as part of MDL-69882. * @return PHPUnit\DbUnit\DataSet\XmlDataSet > *
< * @return PHPUnit\DbUnit\DataSet\XmlDataSet
> * @return phpunit_dataset
protected function createXMLDataSet($xmlFile) {
< return new PHPUnit\DbUnit\DataSet\XmlDataSet($xmlFile);
> debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_files() instead.', DEBUG_DEVELOPER); > return $this->dataset_from_files([$xmlFile]);
} /** * Creates a new CsvDataSet from the given array of csv files. (absolute paths.) *
> * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info. * @param array $files array tablename=>cvsfile > * @todo This will be removed for Moodle 4.2 as part of MDL-69882. * @param string $delimiter > *
< * @param string $delimiter < * @param string $enclosure < * @param string $escape < * @return PHPUnit\DbUnit\DataSet\CsvDataSet
> * @param string $delimiter unused > * @param string $enclosure unused > * @param string $escape unused > * @return phpunit_dataset
protected function createCsvDataSet($files, $delimiter = ',', $enclosure = '"', $escape = '"') {
< $dataSet = new PHPUnit\DbUnit\DataSet\CsvDataSet($delimiter, $enclosure, $escape); < foreach($files as $table=>$file) { < $dataSet->addTable($table, $file); < } < return $dataSet;
> debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_files() instead.', DEBUG_DEVELOPER); > return $this->dataset_from_files($files);
} /** * Creates new ArrayDataSet from given array *
> * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info. * @param array $data array of tables, first row in each table is columns > * @todo This will be removed for Moodle 4.2 as part of MDL-69882. * @return phpunit_ArrayDataSet > *
< * @return phpunit_ArrayDataSet
> * @return phpunit_dataset
protected function createArrayDataSet(array $data) {
< return new phpunit_ArrayDataSet($data);
> debugging(__FUNCTION__ . '() is deprecated. Please use dataset_from_array() instead.', DEBUG_DEVELOPER); > return $this->dataset_from_array($data);
} /** * Load date into moodle database tables from standard PHPUnit data set. *
> * @deprecated since Moodle 3.10 - See MDL-67673 and MDL-64600 for more info. * Note: it is usually better to use data generators > * @todo This will be removed for Moodle 4.2 as part of MDL-69882. * > *
< * @param PHPUnit\DbUnit\DataSet\IDataSet $dataset
> * @param phpunit_dataset $dataset
* @return void */
< protected function loadDataSet(PHPUnit\DbUnit\DataSet\IDataSet $dataset) { < global $DB; < < $structure = phpunit_util::get_tablestructure(); < < foreach($dataset->getTableNames() as $tablename) { < $table = $dataset->getTable($tablename); < $metadata = $dataset->getTableMetaData($tablename); < $columns = $metadata->getColumns(); < < $doimport = false; < if (isset($structure[$tablename]['id']) and $structure[$tablename]['id']->auto_increment) { < $doimport = in_array('id', $columns);
> protected function loadDataSet(phpunit_dataset $dataset) { > debugging(__FUNCTION__ . '() is deprecated. Please use dataset->to_database() instead.', DEBUG_DEVELOPER); > $dataset->to_database();
}
< for($r=0; $r<$table->getRowCount(); $r++) { < $record = $table->getRow($r); < if ($doimport) { < $DB->import_record($tablename, $record); < } else { < $DB->insert_record($tablename, $record); < } < } < if ($doimport) { < $DB->get_manager()->reset_sequence(new xmldb_table($tablename));
> /** > * Creates a new dataset from CVS/XML files. > * > * This method accepts an array of full paths to CSV or XML files to be loaded > * into the dataset. For CSV files, the name of the table which the file belongs > * to needs to be specified. Example: > * > * $fullpaths = [ > * '/path/to/users.xml', > * 'course' => '/path/to/courses.csv', > * ]; > * > * @since Moodle 3.10 > * > * @param array $files full paths to CSV or XML files to load. > * @return phpunit_dataset > */ > protected function dataset_from_files(array $files) { > // We ignore $delimiter, $enclosure and $escape, use the default ones in your fixtures. > $dataset = new phpunit_dataset(); > $dataset->from_files($files); > return $dataset;
}
> } > /** } > * Creates a new dataset from string (CSV or XML). > * /** > * @since Moodle 3.10 * Call this method from test if you want to make sure that > * * the resetting of database is done the slow way without transaction > * @param string $content contents (CSV or XML) to load. * rollback. > * @param string $type format of the content to be loaded (csv or xml). * > * @param string $table name of the table which the file belongs to (only for CSV files). * This is useful especially when testing stuff that is not compatible with transactions. > * @return phpunit_dataset * > */ * @return void > protected function dataset_from_string(string $content, string $type, ?string $table = null) { */ > $dataset = new phpunit_dataset(); public function preventResetByRollback() { > $dataset->from_string($content, $type, $table); if ($this->testdbtransaction and !$this->testdbtransaction->is_disposed()) { > return $dataset;
$this->testdbtransaction->allow_commit();
> $this->testdbtransaction = null; > /** } > * Creates a new dataset from PHP array. } > * > * @since Moodle 3.10 /** > * * Reset everything after current test. > * @param array $data array of tables, see {@see phpunit_dataset::from_array()} for supported formats. * @param bool $reset true means reset state back, false means keep all data for the next test, > * @return phpunit_dataset * null means reset state and show warnings if anything changed > */ * @return void > protected function dataset_from_array(array $data) { */ > $dataset = new phpunit_dataset(); public function resetAfterTest($reset = true) { > $dataset->from_array($data); $this->resetAfterTest = $reset; > return $dataset;
} /** * Return debugging messages from the current test. * @return array with instances having 'message', 'level' and 'stacktrace' property. */ public function getDebuggingMessages() { return phpunit_util::get_debugging_messages(); } /** * Clear all previous debugging messages in current test * and revert to default DEVELOPER_DEBUG level. */ public function resetDebugging() { phpunit_util::reset_debugging(); } /** * Assert that exactly debugging was just called once. * * Discards the debugging message if successful. * * @param null|string $debugmessage null means any * @param null|string $debuglevel null means any * @param string $message */ public function assertDebuggingCalled($debugmessage = null, $debuglevel = null, $message = '') { $debugging = $this->getDebuggingMessages(); $debugdisplaymessage = "\n".phpunit_util::display_debugging_messages(true); $this->resetDebugging(); $count = count($debugging); if ($count == 0) { if ($message === '') { $message = 'Expectation failed, debugging() not triggered.'; } $this->fail($message); } if ($count > 1) { if ($message === '') { $message = 'Expectation failed, debugging() triggered '.$count.' times.'.$debugdisplaymessage; } $this->fail($message); } $this->assertEquals(1, $count); $message .= $debugdisplaymessage; $debug = reset($debugging); if ($debugmessage !== null) { $this->assertSame($debugmessage, $debug->message, $message); } if ($debuglevel !== null) { $this->assertSame($debuglevel, $debug->level, $message); } } /** * Asserts how many times debugging has been called. * * @param int $expectedcount The expected number of times * @param array $debugmessages Expected debugging messages, one for each expected message. * @param array $debuglevels Expected debugging levels, one for each expected message. * @param string $message * @return void */ public function assertDebuggingCalledCount($expectedcount, $debugmessages = array(), $debuglevels = array(), $message = '') { if (!is_int($expectedcount)) { throw new coding_exception('assertDebuggingCalledCount $expectedcount argument should be an integer.'); } $debugging = $this->getDebuggingMessages(); $message .= "\n".phpunit_util::display_debugging_messages(true); $this->resetDebugging(); $this->assertEquals($expectedcount, count($debugging), $message); if ($debugmessages) { if (!is_array($debugmessages) || count($debugmessages) != $expectedcount) { throw new coding_exception('assertDebuggingCalledCount $debugmessages should contain ' . $expectedcount . ' messages'); } foreach ($debugmessages as $key => $debugmessage) { $this->assertSame($debugmessage, $debugging[$key]->message, $message); } } if ($debuglevels) { if (!is_array($debuglevels) || count($debuglevels) != $expectedcount) { throw new coding_exception('assertDebuggingCalledCount $debuglevels should contain ' . $expectedcount . ' messages'); } foreach ($debuglevels as $key => $debuglevel) { $this->assertSame($debuglevel, $debugging[$key]->level, $message); } } } /** * Call when no debugging() messages expected. * @param string $message */ public function assertDebuggingNotCalled($message = '') { $debugging = $this->getDebuggingMessages(); $count = count($debugging); if ($message === '') { $message = 'Expectation failed, debugging() was triggered.'; } $message .= "\n".phpunit_util::display_debugging_messages(true); $this->resetDebugging(); $this->assertEquals(0, $count, $message); } /** * Assert that an event legacy data is equal to the expected value. * * @param mixed $expected expected data. * @param \core\event\base $event the event object. * @param string $message * @return void */ public function assertEventLegacyData($expected, \core\event\base $event, $message = '') { $legacydata = phpunit_event_mock::testable_get_legacy_eventdata($event); if ($message === '') { $message = 'Event legacy data does not match expected value.'; } $this->assertEquals($expected, $legacydata, $message); } /** * Assert that an event legacy log data is equal to the expected value. * * @param mixed $expected expected data. * @param \core\event\base $event the event object. * @param string $message * @return void */ public function assertEventLegacyLogData($expected, \core\event\base $event, $message = '') { $legacydata = phpunit_event_mock::testable_get_legacy_logdata($event); if ($message === '') { $message = 'Event legacy log data does not match expected value.'; } $this->assertEquals($expected, $legacydata, $message); } /** * Assert that an event is not using event->contxet. * While restoring context might not be valid and it should not be used by event url * or description methods. * * @param \core\event\base $event the event object. * @param string $message * @return void */ public function assertEventContextNotUsed(\core\event\base $event, $message = '') { // Save current event->context and set it to false. $eventcontext = phpunit_event_mock::testable_get_event_context($event); phpunit_event_mock::testable_set_event_context($event, false); if ($message === '') { $message = 'Event should not use context property of event in any method.'; } // Test event methods should not use event->context. $event->get_url(); $event->get_description(); $event->get_legacy_eventname(); phpunit_event_mock::testable_get_legacy_eventdata($event); phpunit_event_mock::testable_get_legacy_logdata($event); // Restore event->context. phpunit_event_mock::testable_set_event_context($event, $eventcontext); } /** * Stores current time as the base for assertTimeCurrent(). * * Note: this is called automatically before calling individual test methods. * @return int current time */ public function setCurrentTimeStart() { $this->currenttimestart = time(); return $this->currenttimestart; } /** * Assert that: start < $time < time() * @param int $time * @param string $message * @return void */ public function assertTimeCurrent($time, $message = '') { $msg = ($message === '') ? 'Time is lower that allowed start value' : $message; $this->assertGreaterThanOrEqual($this->currenttimestart, $time, $msg); $msg = ($message === '') ? 'Time is in the future' : $message; $this->assertLessThanOrEqual(time(), $time, $msg); } /** * Starts message redirection. * * You can verify if messages were sent or not by inspecting the messages * array in the returned messaging sink instance. The redirection * can be stopped by calling $sink->close(); * * @return phpunit_message_sink */ public function redirectMessages() { return phpunit_util::start_message_redirection(); } /** * Starts email redirection. * * You can verify if email were sent or not by inspecting the email * array in the returned phpmailer sink instance. The redirection * can be stopped by calling $sink->close(); * * @return phpunit_message_sink */ public function redirectEmails() { return phpunit_util::start_phpmailer_redirection(); } /** * Starts event redirection. * * You can verify if events were triggered or not by inspecting the events * array in the returned event sink instance. The redirection * can be stopped by calling $sink->close(); * * @return phpunit_event_sink */ public function redirectEvents() { return phpunit_util::start_event_redirection(); } /** * Reset all database tables, restore global state and clear caches and optionally purge dataroot dir. * * @param bool $detectchanges * true - changes in global state and database are reported as errors * false - no errors reported * null - only critical problems are reported as errors * @return void */ public static function resetAllData($detectchanges = false) { phpunit_util::reset_all_data($detectchanges); } /** * Set current $USER, reset access cache. * @static * @param null|int|stdClass $user user record, null or 0 means non-logged-in, positive integer means userid * @return void */ public static function setUser($user = null) { global $CFG, $DB; if (is_object($user)) { $user = clone($user); } else if (!$user) { $user = new stdClass(); $user->id = 0; $user->mnethostid = $CFG->mnet_localhost_id; } else { $user = $DB->get_record('user', array('id'=>$user)); } unset($user->description); unset($user->access); unset($user->preference); // Enusre session is empty, as it may contain caches and user specific info. \core\session\manager::init_empty_session(); \core\session\manager::set_user($user); } /** * Set current $USER to admin account, reset access cache. * @static * @return void */ public static function setAdminUser() { self::setUser(2); } /** * Set current $USER to guest account, reset access cache. * @static * @return void */ public static function setGuestUser() { self::setUser(1); } /** * Change server and default php timezones. * * @param string $servertimezone timezone to set in $CFG->timezone (not validated) * @param string $defaultphptimezone timezone to fake default php timezone (must be valid) */ public static function setTimezone($servertimezone = 'Australia/Perth', $defaultphptimezone = 'Australia/Perth') { global $CFG; $CFG->timezone = $servertimezone; core_date::phpunit_override_default_php_timezone($defaultphptimezone); core_date::set_default_server_timezone(); } /** * Get data generator * @static * @return testing_data_generator */ public static function getDataGenerator() { return phpunit_util::get_data_generator(); } /** * Returns UTL of the external test file. * * The result depends on the value of following constants: * - TEST_EXTERNAL_FILES_HTTP_URL * - TEST_EXTERNAL_FILES_HTTPS_URL * * They should point to standard external test files repository, * it defaults to 'http://download.moodle.org/unittest'. * * False value means skip tests that require external files. * * @param string $path * @param bool $https true if https required * @return string url */ public function getExternalTestFileUrl($path, $https = false) { $path = ltrim($path, '/'); if ($path) { $path = '/'.$path; } if ($https) { if (defined('TEST_EXTERNAL_FILES_HTTPS_URL')) { if (!TEST_EXTERNAL_FILES_HTTPS_URL) { $this->markTestSkipped('Tests using external https test files are disabled'); } return TEST_EXTERNAL_FILES_HTTPS_URL.$path; } return 'https://download.moodle.org/unittest'.$path; } if (defined('TEST_EXTERNAL_FILES_HTTP_URL')) { if (!TEST_EXTERNAL_FILES_HTTP_URL) { $this->markTestSkipped('Tests using external http test files are disabled'); } return TEST_EXTERNAL_FILES_HTTP_URL.$path; } return 'http://download.moodle.org/unittest'.$path; } /** * Recursively visit all the files in the source tree. Calls the callback * function with the pathname of each file found. * * @param string $path the folder to start searching from. * @param string $callback the method of this class to call with the name of each file found. * @param string $fileregexp a regexp used to filter the search (optional). * @param bool $exclude If true, pathnames that match the regexp will be ignored. If false, * only files that match the regexp will be included. (default false). * @param array $ignorefolders will not go into any of these folders (optional). * @return void */ public function recurseFolders($path, $callback, $fileregexp = '/.*/', $exclude = false, $ignorefolders = array()) { $files = scandir($path); foreach ($files as $file) { $filepath = $path .'/'. $file; if (strpos($file, '.') === 0) { /// Don't check hidden files. continue; } else if (is_dir($filepath)) { if (!in_array($filepath, $ignorefolders)) { $this->recurseFolders($filepath, $callback, $fileregexp, $exclude, $ignorefolders); } } else if ($exclude xor preg_match($fileregexp, $filepath)) { $this->$callback($filepath); } } } /** * Wait for a second to roll over, ensures future calls to time() return a different result. * * This is implemented instead of sleep() as we do not need to wait a full second. In some cases * due to calls we may wait more than sleep() would have, on average it will be less. */ public function waitForSecond() { $starttime = time(); while (time() == $starttime) { usleep(50000); } } /** * Run adhoc tasks, optionally matching the specified classname. * * @param string $matchclass The name of the class to match on. * @param int $matchuserid The userid to match. */ protected function runAdhocTasks($matchclass = '', $matchuserid = null) { global $CFG, $DB; require_once($CFG->libdir.'/cronlib.php'); $params = []; if (!empty($matchclass)) { if (strpos($matchclass, '\\') !== 0) { $matchclass = '\\' . $matchclass; } $params['classname'] = $matchclass; } if (!empty($matchuserid)) { $params['userid'] = $matchuserid; } $lock = $this->createMock(\core\lock\lock::class); $cronlock = $this->createMock(\core\lock\lock::class); $tasks = $DB->get_recordset('task_adhoc', $params); foreach ($tasks as $record) { // Note: This is for cron only. // We do not lock the tasks. $task = \core\task\manager::adhoc_task_from_record($record); $user = null; if ($userid = $task->get_userid()) { // This task has a userid specified. $user = \core_user::get_user($userid); // User found. Check that they are suitable. \core_user::require_active_user($user, true, true); } $task->set_lock($lock); if (!$task->is_blocking()) { $cronlock->release(); } else { $task->set_cron_lock($cronlock); } cron_prepare_core_renderer(); cron_setup_user($user); $task->execute(); \core\task\manager::adhoc_task_complete($task); unset($task); } $tasks->close(); } }