moodle-phpunit-testing

Moodle PHPUnit Testing

Overview

Moodle ships its own PHPUnit harness with test bootstrap, transactional resets, and data generators. Tests live in <plugin>/tests/<thing>_test.php and extend advanced_testcase. Never call parent::setUp() for DB cleanup — use $this->resetAfterTest().

When to Use

• Writing unit/integration tests for any Moodle plugin or core API
• Debugging test failures (Database was modified errors, isolation issues)
• Adding a data generator (tests/generator/lib.php)
• Testing events, scheduled tasks, ad-hoc tasks, external functions
• Setting up CI for Moodle test suites

Skip when: writing Behat acceptance tests (use moodle-behat-testing).

First-time setup

php admin/tool/phpunit/cli/init.php       # writes phpunit.xml + initializes test DB
vendor/bin/phpunit --testsuite local_example_testsuite

phpunit.xml is regenerated by init.php — never hand-edit. Re-run after installing a new plugin.

Test class skeleton

<?php
namespace local_example;
defined('MOODLE_INTERNAL') || die();

/**
 * @group local_example
 * @covers \local_example\manager
 */
final class manager_test extends \advanced_testcase {

    public function test_create_item(): void {
        $this->resetAfterTest();
        $generator = self::getDataGenerator();
        $course = $generator->create_course();
        $user = $generator->create_user();

        $manager = new manager();
        $id = $manager->create_item($course->id, $user->id, 'hello');

        global $DB;
        $row = $DB->get_record('local_example_items', ['id' => $id], '*', MUST_EXIST);
        $this->assertSame('hello', $row->name);
    }
}

Key rules:

• File name: <thing>_test.php, class: <thing>_test
• final class (Moodle policy since 4.2)
• @covers annotation required by Moodle CS
• @group <component> enables --group filtering
• void return type on test methods, : void on setUp
• self:: (not $this->) for static methods like getDataGenerator()