Перейти к содержимому
M
Все статьи
Разработка 9 мин чтения

PHPUnit для плагина Moodle: настройка, тесты и как не утонуть в фикстурах

Как настроить PHPUnit для плагина Moodle, что в нём тестировать, как писать генераторы данных и избегать громоздких фикстур.

Как настроить PHPUnit для плагина Moodle, что в нём тестировать, как писать генераторы данных и избегать громоздких фикстур.

Тест для плагина 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: после смены версии ядра тестовый набор показывает, что именно сломалось.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.