C++-тесты движка: запуск и диагностика

Сборка с tests=yes, фильтры doctest, регрессии и отличие от тестов проекта.

C++-тесты движка

Эта инструкция относится к тестам исходников движка, а не к C#-тестам игры. Встроенный раннер использует doctest и отдельную точку входа. Тесты проекта и проверки экспортированной игры запускайте отдельно.

Подготовить сборку

Нужны исходники, C++ toolchain и SCons. Работайте из корня дерева Source, где лежат SConstruct и tests/data. Обычный установленный редактор может быть собран без тестов. Наличие C# в редакторе их не включает.

Пример для Windows x64; подготовка toolchain описана в сборке под Windows:

scons platform=windows target=editor arch=x86_64 tests=yes
./bin/reckfell.windows.editor.x86_64.console.exe --test --help

Имя файла зависит от параметров сборки: используйте именно полученный бинарный файл. tests по умолчанию выключен. dev_mode=yes включает его вместе с дополнительными строгими проверками, но явный tests=no может переопределить это. Не включайте весь dev_mode только ради одного теста. Профиль с disable_2d=yes отключает тесты; для этого сценария оставьте обычную конфигурацию редактора.

При наличии тестов --test --help показывает параметры doctest. Отсутствие поддержки даёт ненулевой код завершения и сообщение compiled without support for unit tests. Это отказ запуска, а не успешный прогон с нулём тестов.

Запустить выбранную регрессию

Сначала посмотрите имена, затем выполните выбранные случаи:

PowerShell
./bin/reckfell.windows.editor.x86_64.console.exe --test --list-test-cases --test-case="*[Color]*"
./bin/reckfell.windows.editor.x86_64.console.exe --test --test-case="*[Color]*"
./bin/reckfell.windows.editor.x86_64.console.exe --test --source-file="*test_color.cpp" --success

Шаблоны фильтров заключены в кавычки, чтобы оболочка не раскрыла *. Метки [Color] — часть имени, не отдельное поле тега. --success добавляет успешные проверки в вывод и обычно нужен только при разборе проблемы. Убедитесь, что фильтр действительно выбрал тесты: код 0 при пустой выборке не доказывает проверку функции.

Для XML-отчёта:

PowerShell
./bin/reckfell.windows.editor.x86_64.console.exe --test --test-case="*[Color]*" --reporters=xml --out=color-tests.xml
if ($LASTEXITCODE -ne 0) { throw "C++ tests failed" }

Сохраняйте отчёт вместе с параметрами сборки и идентичностью бинарного файла. Успех выбранной группы не означает успех всего набора, экспортного шаблона или другой платформы. Чтобы запустить доступный набор без фильтров, используйте --test. Пропускаемые тесты включаются отдельно через --no-skip; не добавляйте этот флаг без необходимости.

Добавить проверку

Создайте, например, tests/core/math/test_color_clamp_regression.cpp. Это новый файл исходников, не файл проекта игры. Имя в TEST_FORCE_LINK должно совпасть с именем файла без .cpp и быть уникальным:

C++
#include "tests/test_macros.h"
#include "core/math/color.h"

TEST_FORCE_LINK(test_color_clamp_regression)

namespace TestColorClampRegression {
TEST_CASE("[ColorClampRegression] Clamp all RGBA channels") {
    const Color input(2.0f, -1.0f, 0.5f, 2.0f);
    const Color result = input.clamp();
    CHECK(result.is_equal_approx(Color(1.0f, 0.0f, 0.5f, 1.0f)));
    CHECK(input.is_equal_approx(Color(2.0f, -1.0f, 0.5f, 2.0f)));
}
} // namespace TestColorClampRegression

Проверка задаёт ожидаемое ограничение всех RGBA-каналов и отсутствие изменения входного значения. Пересоберите свой тестовый редактор и отберите *[ColorClampRegression]*. Этот пример сверён с текущими C++-исходниками; отдельная сборка движка с новым файлом здесь не выполнялась.

tests/SCsub собирает вложенные .cpp и создаёт ссылки на их TEST_FORCE_LINK. Для модульных тестов есть отдельная регистрация: см. C++-модули. Не создавайте второй файл с тем же force-link именем.

Писать полезные утверждения

Макрос	Когда применять
`REQUIRE`	Условие необходимо для продолжения текущего случая: например, объект создан. При ошибке текущий случай прерывается.
`CHECK`	Проверка результата; при ошибке следующие утверждения продолжаются, но прогон считается неуспешным.
`WARN`	Только предупреждение. Не используйте вместо проверки обязательного поведения.
`SUBCASE`	Альтернативная ветвь общего setup. Тело теста выполняется заново для каждой ветви.

Проверяйте нормальный результат, границу и воспроизведение исправленной ошибки. Для float используйте соответствующее приблизительное сравнение. Ошибку сначала воспроизведите на старом поведении: тест, который проходит и до исправления, может не проверять регрессию.

Тесты, требующие дерева Entity или редактора, используют специальные имена [EntityTree] и [Editor]; [Audio] создаёт аудиосервер с фиктивным драйвером. Это специальная логика текущего раннера, не универсальные атрибуты doctest. Для точного окружения смотрите tests/test_main.cpp; фиктивное окно или аудиодрайвер не проверяет реальный GPU или устройство вывода.

Если запуск не работает

Нет поддержки тестов: запущен обычный редактор либо сборка была без tests=yes. Проверьте фактический путь бинарного файла.
Test data not found: текущая папка не содержит tests/data. Запускайте из корня Source; часть данных также ищется рядом с bin.
Найдено 0 тестов: проверьте список имён, фильтр, пересборку и уникальный TEST_FORCE_LINK.
Ошибка проверки: сохраните код завершения, конкретное утверждение и параметры сборки. Не заменяйте CHECK на WARN, чтобы получить зелёный результат.
Ожидаемая ошибка засоряет лог: временные ERR_PRINT_OFF / ERR_PRINT_ON меняют глобальный вывод. Восстанавливайте его до любого возможного раннего выхода; при REQUIRE внутри отключённого участка восстановление может не произойти.

Раннер использует временную папку reckfell_test в системном кеше и очищает её содержимое в начале запуска. Не храните там свои данные. Это не рабочая папка проекта.