test/.template/development/docs/adr/0006-visual-regression.md

ADR-0006: Трёхуровневая стратегия регрессионного тестирования

Дата: 2026-08-26 Статус: Принято

Контекст

Шаблон содержит хрупкую пагинацию, сложные таблицы, подписи, формулы, кириллическую нумерацию и show rules. Успешная компиляция не обнаруживает тихий перенос строки, наложение печати или изменение количества страниц. Чистый pixel-perfect diff, в свою очередь, слишком чувствителен к версии renderer и системным шрифтам.

Рассматриваемые варианты

1. Проверять только exit code компилятора — быстро, но не защищает макет.
2. Использовать только pixel-perfect snapshots — ловит всё, но создаёт шум при допустимых изменениях окружения.
3. Совместить unit, semantic и visual проверки — больше инфраструктуры, зато дефекты классифицируются точнее.

Решение

Выбрали три уровня тестов:

1. Domain unit tests через typst eval и assert.
2. Compile/semantic tests: exit code, diagnostics, A4, количество страниц, наличие обязательных текстовых маркеров и PDF metadata.
3. Visual regression: rasterize через Poppler, сравнивать контрольные области и полный perceptual diff с документированным порогом.

Snapshots создаются только из синтетического test-company; реальные подписи и печати не включаются в публичные тестовые изображения. Новая версия Typst всегда проверяется отдельным прогоном до обновления snapshots.

Последствия

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

Становится сложнее: требуется Python/Poppler test runtime и процедура осознанного обновления эталонов.

Закрывает дверь на: автоматическое принятие новых snapshots при обычном тестовом запуске.