Тест для плагина Moodle пишется один раз, а окупается при каждом обновлении ядра и каждой правке кода. Я начала писать PHPUnit-тесты к своим плагинам после того, как обновление с одной ветки Moodle на другую молча сломало расчёт в отчёте: вручную этого никто не заметил, пока цифры не увидел заказчик. Ниже — как подготовить окружение, что именно проверять в плагине и как держать фикстуры под контролем.
Что тестирует PHPUnit в Moodle и чем он отличается от обычного
В Moodle PHPUnit работает не с вашей рабочей базой. Для тестов создаётся отдельная установка: свои таблицы с другим префиксом и свой каталог данных. Перед каждым тестом, где вы это попросите, система откатывает изменения в базе, поэтому тесты не мешают друг другу и не трогают рабочие данные. Это принципиальный момент: нельзя «просто запустить phpunit» на боевой копии — нужна отдельная конфигурация.
Подробности описаны в официальной документации: moodledev.io — PHPUnit. Здесь — то, что я делаю на практике.
Подготовка окружения шаг за шагом
Нужны три вещи: зависимости разработчика через Composer, две строки в config.php и инициализация тестовой среды.
// config.php — добавить до строки с require_once(__DIR__ . '/lib/setup.php')
$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/var/www/phpunit_data';
Префикс должен отличаться от основного префикса таблиц, а каталог данных — лежать вне основного moodledata и быть доступным на запись пользователю, под которым вы запускаете тесты. Затем:
composer install
php admin/tool/phpunit/cli/init.php
vendor/bin/phpunit --testsuite local_myplugin_testsuite
Команда init.php создаёт тестовые таблицы и собирает файл phpunit.xml со списком наборов тестов всех плагинов, у которых есть каталог tests. Если вы добавили плагин или первый тестовый файл, а набор не находится, нужно запустить инициализацию снова — либо пересобрать только конфигурацию командой php admin/tool/phpunit/cli/util.php --buildconfig. Если после обновления ядра тесты ругаются на версию тестовой среды, это тоже лечится повторной инициализацией.
Где лежат тесты и как называются
| Что | Где | Правило |
|---|---|---|
| Тестовые классы | local/myplugin/tests/ | имя файла заканчивается на _test.php, класс наследует advanced_testcase |
| Пространство имён | в начале файла | по компоненту плагина, например namespace local_myplugin; |
| Генераторы данных плагина | tests/generator/lib.php | класс local_myplugin_generator на базе component_generator_base |
| Общие вспомогательные классы | tests/fixtures/ | всё, что не является тестом и не должно запускаться |
| Конфигурация набора | генерируется | руками phpunit.xml не правят, он пересобирается |
Первый тест: что в нём обязательно
Минимальный тест выглядит так: создаём курс и пользователя, записываем его, вызываем код плагина, проверяем результат.
namespace local_myplugin;
/**
* @covers \local_myplugin\manager
*/
final class manager_test extends \advanced_testcase {
public function test_counts_enrolled_students(): void {
$this->resetAfterTest();
$this->setAdminUser();
$generator = $this->getDataGenerator();
$course = $generator->create_course();
$user = $generator->create_user();
$generator->enrol_user($user->id, $course->id, 'student');
$manager = new manager();
$this->assertSame(1, $manager->count_students($course->id));
}
}
Две строки здесь не опциональны. resetAfterTest() говорит системе вернуть базу и глобальные настройки в исходное состояние после теста; без неё следующий тест получит «грязные» данные, а Moodle выдаст предупреждение об изменённом состоянии. setAdminUser() или setUser() задаёт, от чьего имени выполняется код, ведь многие функции проверяют права текущего пользователя.
Что тестировать в плагине, а что не надо
Проверять стоит то, что ломается незаметно и стоит дорого при ошибке.
- Расчёты и правила. Итоговые оценки, сроки, статусы, фильтрация. Это чистая логика, она тестируется быстрее всего.
- Права. Что студент не видит чужие записи, а куратор видит только свою группу. Для этого создают пользователя с нужной ролью и вызывают код от его имени, ожидая исключение.
- Работа с базой. Запросы с условиями и объединениями, особенно если плагин должен работать на MySQL, MariaDB и PostgreSQL.
- Внешние функции и веб-сервисы. Параметры и структура ответа.
- Задачи по расписанию. Можно создать объект задачи и вызвать
execute()напрямую. - Обработчики событий. Вызвать событие и проверить побочный эффект.
Не нужно тестировать код ядра Moodle (он уже покрыт) и оформление страниц. Для проверки «кнопка нажимается и открывается нужная страница» лучше подходит Behat — я описывала его в статье про Behat в Moodle.
Провайдеры данных и исключения
Когда одна и та же проверка идёт на десяток входных значений, пользуйтесь провайдером данных: отдельный статический метод возвращает массив наборов, тест получает их через аргументы. Каждому набору дайте осмысленный ключ, он попадёт в отчёт о падении.
/**
* @dataProvider grade_scale_provider
*/
public function test_grade_to_mark(float $percent, int $expected): void {
$this->assertSame($expected, scale::to_mark($percent));
}
public static function grade_scale_provider(): array {
return [
'ниже порога' => [49.9, 2],
'ровно порог' => [50.0, 3],
'максимум' => [100.0, 5],
];
}
Для проверки исключений вызывайте expectException() до кода, который должен упасть, и при необходимости expectExceptionMessage(). Для прав чаще всего ожидают required_capability_exception.
Как не утонуть в фикстурах
Больше всего времени уходит не на сами проверки, а на подготовку данных. Что помогает:
- Генератор плагина. Если у плагина есть собственные таблицы, заведите в
tests/generator/lib.phpметод видаcreate_record()со значениями по умолчанию. Тогда тест указывает только то, что для него важно. - Один тест — одна причина падения. Не собирайте в одном методе сценарий на двадцать шагов.
- Данные создаются в самом тесте. Общий
setUp()со сложной подготовкой быстро превращается в загадку. Если подготовка нужна многим тестам, вынесите её в приватный метод с понятным именем. - Не тянуть реальный набор. Выгрузки из 1С и большие CSV не годятся в фикстуры. Для разбора формата достаточно файла на три строки в
tests/fixtures/. - Время и случайность. Если логика зависит от «сегодня», передавайте дату параметром, а не вызывайте
time()внутри; так тест не зависит от дня запуска.
Частые ошибки при запуске
| Симптом | Причина | Что сделать |
|---|---|---|
| «Not a PHPUnit test environment» | тестовая среда не инициализирована | выполнить init.php |
| Тесты нового плагина не находятся | конфигурация собрана до его появления | пересобрать конфигурацию или повторить инициализацию |
| Тест проходит один, падает в наборе | нет resetAfterTest() или состояние осталось в статической переменной | добавить сброс, не хранить состояние в статических свойствах |
| Ошибка прав на каталог данных | каталог создан другим пользователем | выдать права тому, кто запускает тесты |
| Версия БД в тестовой среде устарела | обновили код, а среду не пересобрали | повторная инициализация |
Чек-лист перед тем, как считать плагин покрытым
- Есть тест на каждое публичное правило расчёта и каждый запрос с условием.
- Проверено поведение для пользователя без прав.
- Тесты не зависят от порядка запуска и текущей даты.
- В каждом тестовом классе есть аннотации
@covers: так видно, какой код проверяется. - Набор запускается одной командой и проходит на тех версиях Moodle и PHP, которые указаны в
version.php. - Прогон встроен в CI или хотя бы в привычку перед релизом (см. статью про стандарты кода и Code Checker).
Как запускать выборочно и быстро
Весь набор Moodle гонять не нужно. Во время работы я запускаю один файл или один метод, а полный набор плагина — перед коммитом.
vendor/bin/phpunit local/myplugin/tests/manager_test.php
vendor/bin/phpunit --filter test_counts_enrolled_students local/myplugin/tests/manager_test.php
vendor/bin/phpunit --testsuite local_myplugin_testsuite
Если тест падает, а причина не ясна, добавьте в начало теста временный вывод через var_dump и смотрите именно на состояние данных, а не на текст исключения: в половине случаев проблема в том, что фикстура создала не то, что вы ожидали, например пользователя без записи на курс.
Версии PHP и баз данных
Плагин, который собирается работать у разных заказчиков, должен проходить тесты на нескольких базах. Запросы с нестандартным SQL ведут себя по-разному в MySQL, MariaDB и PostgreSQL: регистр в сравнении строк, группировка, приведение типов. Я запускаю набор хотя бы на двух базах; удобнее всего это делать в контейнерах, переключая базу и версию PHP переменными окружения (об этом в статье про moodle-docker). Если плагин пишет в базу через API Moodle и не использует собственный SQL, риск ниже, но проверять всё равно стоит.
Тесты для того, что уже написано без тестов
С нуля писать тесты легко, сложнее с плагином, которому три года и который никто не покрывал. Здесь я не пытаюсь охватить всё. Начинаю с места, где последний раз была ошибка: пишу тест, который воспроизводит её, убеждаюсь, что он падает, исправляю код и оставляю тест как защиту. Через несколько таких итераций набор вырастает именно там, где код хрупкий. Если логика зашита в длинные функции со страницы, сначала выделяю её в отдельный класс в classes/ с понятными входными данными: страницы и формы тестировать неудобно, а класс — легко. Этот шаг сам по себе полезнее любого количества тестов поверх запутанного кода.
Если вы заказываете разработку плагина Moodle и хотите получить его с тестами, об этом лучше договориться в техническом задании: тесты требуют времени, но резко снижают стоимость последующих обновлений. А если плагин уже есть и тестов нет, обычно начинают с самых дорогих при ошибке мест — расчётов и прав — и расширяют покрытие по мере правок. Это же хорошо ложится на задачи обновления Moodle: после смены версии ядра тестовый набор показывает, что именно сломалось.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.