Sprinter-SDCC/applications/SprPoP/docs/host_tests_plan.md

План: модульные тесты движка SprPoP под ucsim_z80

Обвязка общая — testkit/ в корне репозитория (там же объяснение, почему прогон именно под z80, а не хостовым gcc). Наборы лежат в ../SprPoP/tests-host/.

Задача плана: перестать чинить одно и то же дважды. За два прогона уровня 1 (2026-08-03) закрыто восемь корней, и часть из них — регрессии соседней механики, внесённые предыдущим фиксом. Такие вещи ловятся тестом за миллисекунды, а в MAME — часами ручного вождения Кида.

Что уже есть

набор	модуль	статус
t_geom	pop_geom.c	39 проверок, включая побитовую сверку asm-LCG с 32-битной формулой на 128 шагах

pop_geom.c выбран первым, потому что не тянет ничего за собой. Дальше начинаются швы.

Фаза 1. Два шва (блокирует всё остальное)

1.1 Доступ к странице уровня

pop_level.c ходит по абсолютным адресам: gfx_w0_map(lvl_page), затем разыменование (uint8_t *)(LVL_DATA_OFF + …). В тестовом бинаре это обращение в никуда.

Нужен макрос W0PTR(off):

• на таргете — ((uint8_t *)(off)), то есть ровно как сейчас;
• в тестах — смещение в обычном массиве-подложке.

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

Тестовая подложка должна уметь: загрузить синтетическую комнату (10×3 байта fg + mod) и целый синтетический уровень на 24 комнаты, чтобы проверять межкомнатные вещи.

1.2 Журналирующий рендерер

Вместо pop_bg.c/pop_cdraw.c в тестовый бинарь линкуется модуль с теми же прототипами, который не рисует, а записывает вызовы: какой тайл помечен к перерисовке, каким кодом, с каким счётчиком страниц.

Это не обход проблемы, а самостоятельная ценность: BUG-GATE-ANIM-1 был ровно такой формы — ворота меняли состояние, но пометка на перерисовку не ставилась. Проверяется утверждением, а не глазами.

Минимум, который надо перехватывать: pop_set_redraw, pop_set_redraw_above, pop_loose_mob_spawn, pop_gate_redraw.

Фаза 2. Регрессионные кейсы из BUGS_CLOSED.md

После швов BUGS_CLOSED.md превращается в готовую спецификацию: у каждой записи есть симптом и ожидаемое поведение. Кандидаты, которые ловятся логикой (без отрисовки и без железа):

баг	что закрепить тестом
BUG-LVLSTATE-1	запись тайла переживает выход из комнаты
BUG-RESPAWN-1	рестарт уровня возвращает ВСЕ тайлы из эталонной копии
BUG-RESPAWN-2	рестарт возвращает таблицу стражей; убитый снова жив
BUG-GATE-ANIM-1	смена состояния ворот ставит пометку POP_RD_GATE; закрывающиеся — на обе страницы, открывающиеся — на одну
BUG-COLL-1	check_collisions сканирует ряд справа налево и выбирает НАИМЕНЬШУЮ занятую колонку
BUG-STANDUP-1	bumped_floor у трупа (alive >= 0) только выравнивает и не трогает последовательность
BUG-DEATH-1	hitp_curr == 0 при живом Киде переводит его в «умирает» ровно один раз
BUG-LOOSE-2	кусок, начавший падать, долетает и кладёт щебень ПОСЛЕ смены комнаты
BUG-CEIL-2	loose-плита ряда 2 верхнего соседа живёт как «ряд −1»

BUG-LOOSE-2 стоит взять первым: он до сих пор помечен в BUGS_OPEN.md как непроверенный именно потому, что гонку «уйти из комнаты раньше, чем долетит плита» через мост MAME воспроизвести не удалось. На уровне логики это несколько строк — заспавнить кусок, сменить комнату, тикать до приземления, проверить щебень в данных уровня.

Не берутся (нужна картинка либо железо): BUG-DOOR-CLIP, BUG-CEIL-1, BUG-CEIL-3, BUG-OCCL-1, BUG-KBD-4, BUG-3.

Фаза 3. Сценарные тесты

Сейчас шаг кадра размазан по main() в sprpop.c. Вынести его в pop_frame_tick() — тогда появляются тесты вида «поставить Кида в известное состояние, скормить N тиков ввода, проверить итог»:

дано:  комната 5, Кид на кнопке (0,6)
когда: 40 тиков без ввода
тогда: комната по-прежнему 5, Кид на полу ряда 2

Это тот самый BUG-STANDUP-1, который ловили потиковой трассой в MAME.

Ввод подаётся не через kbd_raw_down(), а через подменяемый источник — это же даст возможность проигрывать записанные сценарии.

Фаза 4. Дифф против SDLPoP

SDLPoP/src/ лежит в дереве, собирается на хосте, и там уже стоят отладочные трассы (DBG kidobj tilepos=… в seg008, DBG make_loose_fall в seg007). Значит эталон можно заставить печатать потиковую трассу автоматически.

Схема: общий формат скрипта ввода и общий формат трассы (тик, frame, x, y, room, col, row, action, alive, hp). Гоняем обе реализации, диффим, первое расхождение — номер тика и есть баг. Это ровно то, что делалось руками через MAME, только бесплатно и повторяемо: BUG-COLL-1 и BUG-STANDUP-1 такой дифф нашёл бы за секунды.

Лицензия. SDLPoP — GPLv3, правило подпроекта — читать и переписывать, не линковать. Оракул обязан быть отдельным исполняемым файлом, общающимся через файлы трасс, а не слинкованным с нашим кодом в один бинарь.

Требование к детерминизму: сиды PRNG должны совпадать. У нас POP_PRANDOM_EXACT даёт ту же последовательность, что в оригинале, и это уже закреплено тестом geom_lcg_matches_reference.

Чего эти тесты не поймают

Отрисовку, банки и W-окна, тайминги, клавиатуру — за этим остаётся MAME.

И отдельный класс: баги порядка вызовов. Свежий пример — окно fore-клипа (pop_fore_set_clip) одно на всех, и его ставит каждый, кто рисует персонажа; когда порядок «Кид/страж» стал переменным, окно осталось стражьим, и Кид нарисовался поверх передних столбов. Это не «функция вернула не то», unit-тест такое не видит. Ловится инвариантом, вкомпилированным в safe-сборку: «в момент pop_fore_over_char окно клипа принадлежит Киду». Отдельный инструмент, дополняющий тесты.

Порядок работ

1. Шов W0PTR + подложка уровня.
2. Журналирующий рендерер.
3. BUG-LOOSE-2 — закрыть висящий вопрос.
4. Остальные кейсы из таблицы фазы 2.
5. pop_frame_tick() + сценарные тесты.
6. Дифф против SDLPoP.

Правило приёмки: тест не считается написанным, пока не проверен мутацией — сломать проверяемое место и убедиться, что набор краснеет.