Автоматизированное тестирование и проверка

Автоматизированное тестирование проверяет код и содержимое Defold с помощью явных, машиночитаемых свидетельств. Это руководство поможет проектировать тесты, одинаково пригодные для локальных скриптов, исполнителей CI (Continuous Integration) и агентов для программирования. Оно охватывает тесты модулей, запуск коллекций, браузерные тесты, автоматизацию среды выполнения, визуальные проверки и headless-сборки, а также содержит полезные практические рекомендации.

Уровни проверки

Хорошая система автоматизированного тестирования следует принципам пирамиды тестирования, разделяющей тесты на три основных уровня: модульные, интеграционные и сквозные (E2E). В Defold тесты можно разделить на отдельные коллекции, загружаемые при начальной загрузке. Обычно лучше начинать с самой узкой и быстрой проверки, способной обнаружить проблему, а затем при необходимости добавлять тесты среды выполнения или платформы.

Успешная компиляция доказывает, что проект собирается, но не доказывает правильность игрового процесса. Снимок экрана не подтверждает сложные переходы, анимации, взаимодействия или ход игры, однако современные мультимодальные решения могут по нему исследовать, как выглядел один кадр, и проверить правильность шейдеров и визуального макета. Для автоматизированных тестов всё же отдавайте предпочтение детерминированным утверждениям, когда условие можно выразить непосредственно.

Повторно используемый и тестируемый код Lua

Храните повторно используемую логику в модулях Lua с минимальными зависимостями от движка. Тогда чистые преобразования данных, правила, конечные автоматы и вычисления можно проверять без создания полноценного игрового мира.

Отделяйте код, взаимодействующий с движком, от вызываемой им логики. Скрипт может преобразовывать сообщения и состояние компонентов в вызовы модуля, а тесты — напрямую вызывать модуль с контролируемыми входными данными.

Подробнее см. в руководстве «Написание кода».

Тесты в запущенной коллекции

Используйте отдельную тестовую коллекцию, когда поведение зависит от игровых объектов, компонентов, сообщений, ввода, физики или других систем движка.

Каждый тест должен:

1. установить известное состояние;
2. выполнить одно действие;
3. утвердить и оценить ожидаемый результат;
4. очистить созданные ресурсы;
5. вывести структурированное описание результата.

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

[bootstrap]
main_collection = /test/test.collectionc

Не оставляйте временную тестовую коллекцию начальной загрузки в обычной конфигурации проекта. В CI предпочтительно передавать Bob отдельный файл настроек. CI не должен изменять состояние репозитория; временные изменения допустимы только при необходимости.

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

Фреймворки тестирования

Проект может реализовать небольшой исполнитель тестов или использовать библиотеку тестирования от сообщества.

Например, DefTest — библиотека модульного тестирования на основе Telescope. Она поддерживает наборы тестов, функции настройки и очистки, утверждения, фильтрацию по именам, моки для выбранных API Defold и необязательное покрытие LuaCov. Тесты можно запускать из отдельной коллекции начальной загрузки, в том числе в headless-бандле, созданном с помощью Bob.

Структурированные результаты тестов

Сводка фреймворка в консоли или журнале может быть полезна разработчикам, но автоматическому контроллеру без участия человека всё равно нужен явный результат завершения. При необходимости добавьте небольшую обёртку вокруг callback-функции или сводки фреймворка, чтобы контроллер мог легко обработать результаты тестов.

Простое описание результатов может использовать уникальный префикс, за которым в каждой физической строке консоли следует один объект JSON:

TEST {"run":"8f13","event":"suite_start","tests":2}
TEST {"run":"8f13","event":"case","name":"player_moves","status":"pass","duration_ms":3}
TEST {"run":"8f13","event":"case","name":"player_stops","status":"pass","duration_ms":2}
TEST {"run":"8f13","event":"suite_end","status":"pass","passed":2,"failed":0}

Сборщик должен обрабатывать каждую строку независимо, находить префикс TEST, разбирать следующий за ним JSON и игнорировать посторонний вывод движка.

Включайте уникальный идентификатор запуска, чтобы вывод старого или параллельного процесса не мог завершить текущий запуск. Каждый набор тестов должен выдавать одно однозначное финальное событие (например, Pass, Failure, Crash, Timeout и т. п.).

Сбор вывода консоли

Когда игра запускается из редактора, он предоставляет как текущую историю консоли, так и непрерывный поток. Закрывайте поток после соответствующего события завершения набора тестов, остановки процесса, ошибки либо по достижении заданного тайм-аута или ограничения числа строк.

Подробнее см. в руководстве по HTTP API редактора.

Сохраняемые журналы

Defold также может сохранять журнал игры, если включить параметр Write Log File в game.project. См. Журналы игры и системы. Журналирование в файл полезно для упакованных приложений и тестирования на целевых устройствах, где консоль редактора недоступна.

Проект может использовать встроенные функции print() и pprint() или, например, любую другую библиотеку журналирования с нашего портала ассетов.

Тестирование запущенной игры через API среды выполнения

API автоматизации среды выполнения может исследовать работающий отладочный движок и управлять им. Его можно использовать, когда тестам требуется находить объекты среды выполнения, внедрять ввод, ожидать видимого состояния или захватывать отрисованный результат.

Подробнее см. в руководстве по сервису движка.

В следующем примере используется структура вспомогательной библиотеки Python для Automation Bridge. Проект должен включать совместимую версию отладочного расширения, предоставлять элемент с заданным идентификатором автоматизации и публиковать состояние приложения screen:

from automation_bridge import editor

project = editor.open_project(".")
game = project.build_and_run()

try:
    play = game.element(automation_id="play_button")
    game.click(play)
    game.wait_for_state("screen", "gameplay", timeout=5.0)
    screenshot = game.screenshot()
    print(screenshot.path)
finally:
    game.close_engine()

Определяемые приложением состояния и идентификаторы автоматизации используют необязательный отладочный Lua API Automation Bridge, который проект должен включить и публиковать. Фиксированная задержка чувствительна к скорости машины и таймингу кадров; ограниченный по времени опрос определённого состояния надёжнее.

Automation Bridge — расширение, а не часть ядра движка. Обращайтесь к его справочнику Python API для получения сведений о селекторах, ожиданиях, состояниях, событиях, снимках экрана и диагностике установленной версии.

Браузерные тесты для HTML5

Редактор может создать и предоставить HTML5-сборку с помощью актуальной команды build-html5, как описано в руководстве по HTTP API редактора. Bob также может создать HTML5-бандл без редактора.

Внешние инструменты автоматизации браузера, такие как Playwright, Puppeteer, Selenium, WebdriverIO или Cypress, могут:

• ожидать готовности Canvas Defold и приложения;
• отправлять ввод с клавиатуры, мыши и эмулируемый сенсорный ввод;
• изменять размер области просмотра;
• собирать вывод консоли браузера и ошибки JavaScript;
• делать снимки экрана и сравнивать артефакты.

Ввод, направленный в Canvas, обрабатывается через обычные привязки ввода проекта и callback-функции on_input(). Тестируйте как отклик игры, так и точки интеграции, специфичные для браузера.

Самый надёжный подход — предоставить явный тестовый мост JavaScript в пользовательском index.html. На стороне Defold HTML5-сборки могут выполнять JavaScript с помощью html5.run(), что делает возможной связь с таким мостом на стороне браузера. Для команд, передаваемых из JavaScript обратно в Defold, используйте отдельный мост между JavaScript и движком.

Ограничивайте браузерные тесты по времени. В итоговом отчёте различайте ошибку загрузки страницы, отсутствие Canvas, ошибку JavaScript, тайм-аут теста и неудачное игровое утверждение.

Предпросмотры редактора и снимки экрана среды выполнения для визуальной инспекции

Можно создавать снимки экрана файлов ресурсов в стандартном представлении сцены открытого редактора или запущенной игры.

Сравнение изображений можно использовать, например, для регрессионных тестов. При неудачной проверке сохраняйте изображение различий и метрики сравнения.

Мультимодальная модель может оценивать в ходе визуальной инспекции семантические условия, которые трудно выразить иначе: обрезанный текст, перекрывающиеся элементы управления, неясные состояния выбора или содержимое за пределами безопасной области. Рекомендуется считать такую оценку дополнительным сигналом с явными критериями, но не заменой детерминированным проверкам логики или сравнению изображений.

Headless-тесты и CI

Для CI, не зависящей от редактора, используйте инструмент командной строки Bob.

С его помощью можно разрешать зависимости, собирать игру, архив или автономный бандл, а также создавать отчёт JSON:

mkdir -p build/reports

java -jar bob.jar \
  --root . \
  --archive \
  --build-report-json build/reports/build-report.json \
  resolve build

Создайте headless-бандл для тестов с отдельными настройками:

java -jar bob.jar \
  --root . \
  --settings test/test.settings \
  --platform x86_64-linux \
  --variant headless \
  --archive \
  --bundle-output build/test-bundle \
  resolve build bundle

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

Руководство по Bob описывает платформы, файлы настроек, бандлы, кэши, нативные расширения и отчёты о сборке.

Отчёты об ошибках и артефакты

Хорошие результаты тестов должны сохранять достаточно свидетельств для воспроизведения и диагностики ошибки:

• имя теста, идентификатор запуска и подробности утверждения;
• затраченное время и классифицированный результат;
• полный журнал консоли или процесса;
• версию Defold, целевую платформу и соответствующую конфигурацию;
• отчёт о сборке Bob и статус завершения процесса;
• состояние среды выполнения или снимок сцены, если доступны;
• снимки экрана, различия с эталоном, записи или трассировки браузера;
• пути или ссылки на все сгенерированные артефакты.

Один и тот же формат должен быть пригоден для разработчика, локального скрипта, сервиса CI или ИИ-агента для программирования. Это сохраняет проверку детерминированной, даже когда диагностика или исправление делегированы.