Автоматизоване тестування й перевірка

Автоматизоване тестування перевіряє код і вміст Defold за допомогою явних, придатних для машинного опрацювання доказів. Використовуйте цей посібник, щоб проєктувати тести, які однаково працюють із локальними скриптами, засобами запуску CI (Continuous Integration) й агентами програмування. Він охоплює тести модулів, запущені колекції, браузерні тести, автоматизацію середовища виконання, візуальні перевірки, збирання без графічного інтерфейсу та містить корисні рекомендації.

Рівні перевірки

Належні рівні автоматизованого тестування відповідають моделі піраміди тестування, яка поділяє тести на три основні шари: модульні, інтеграційні й наскрізні (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. Тести можна запускати зі спеціальної початкової колекції, зокрема в пакеті без графічного інтерфейсу, створеному за допомогою Bob.

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

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

Простий опис результатів може використовувати унікальний префікс, після якого в кожному фізичному рядку консолі міститься один об’єкт 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()

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

Automation Bridge — це розширення, а не частина основного рушія. Зверніться до його довідника Python API, щоб дізнатися про селектори, очікування, стан, події, знімки екрана й діагностику для встановленої версії.

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

Редактор може створити й обслуговувати збірку HTML5 за допомогою поточної команди build-html5, як описано в посібнику з HTTP API редактора. Bob також може створити пакет HTML5 без редактора.

Зовнішні засоби автоматизації браузера, як-от Playwright, Puppeteer, Selenium, WebdriverIO або Cypress, можуть:

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

Введення, спрямоване на полотно, опрацьовується через звичайні прив’язки введення проєкту й зворотні виклики on_input(). Перевіряйте як реакцію гри, так і специфічні для браузера точки інтеграції.

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

Обмежуйте браузерні тести. У підсумковому звіті розрізняйте збій завантаження сторінки, відсутнє полотно, помилку JavaScript, тайм-аут тесту й невиконане ігрове твердження.

Попередні перегляди редактора й знімки екрана середовища виконання для візуального інспектування

Можна створити знімок екрана файлів ресурсів у стандартному перегляді сцени відкритого редактора або гри під час виконання.

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

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

Тести без графічного інтерфейсу та CI

Для незалежного від редактора CI використовуйте засіб збирання Bob із інтерфейсом командного рядка.

Він дає змогу розв’язувати залежності, збирати гру, архів або автономний пакет і генерувати звіт JSON:

mkdir -p build/reports

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

Створіть тестовий пакет без графічного інтерфейсу зі спеціальними налаштуваннями:

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 або агента програмування ШІ. Це зберігає перевірку детермінованою, навіть коли діагностування чи виправлення делеговано.