HY2XS_flamy/docs/11-testing-and-acceptance.md

Testing and acceptance

Цель документа

Зафиксировать checklist для новой двухслойной схемы.

A. Builder layer tests

Проверяем

1. builder запускается на Debian 13 amd64 build host
2. итоговый пакет собирается без target-side шагов
3. bundled HY2XS admin реально входит в пакет
4. package metadata / build id присутствуют
5. compiled Bun/TypeScript orchestrator artifact присутствует
6. в пакет не попадает build-мусор
7. builder сам доставляет отсутствующие build-зависимости
8. builder проверяет версии Go/Bun/Node.js/pnpm
9. builder пишет версии toolchain в metadata

B. Target install tests

На чистом Debian 13 проверяем

1. пакет запускается без ручной сборки на сервере
2. Hysteria2 скачивается с official upstream
3. bundled HY2XS admin раскладывается локально из пакета
4. создаются нужные каталоги
5. создаются systemd unit-файлы
6. создаются hy2xs.env и post-install.env с правами 0600 root:root
7. baseline firewall применяется корректно через staged mode
8. SSH остаётся доступным
9. reconfigure --dry-run выводит план изменений
10. reconfigure --apply применяет изменения и проходит smoke

C. Runtime tests

1. hysteria-server active
2. hy2xs-admin active
3. Hysteria слушает только IPv4 (0.0.0.0:<udp_port>)
4. HY2XS admin слушает ожидаемый HY2XS_UI_BIND_HOST:<ui_port>
5. тестовый совместимый клиент подключается
6. идёт реальный трафик
7. лимит 50/50 Mbps соблюдается при согласованной клиентской конфигурации
8. reboot не ломает baseline
9. Hysteria2 управляется systemd unit, а не внутренним updater'ом admin panel
10. нет IPv6 listen ([::]) для Hysteria/HY2XS admin
11. trafficStats.secret не равен JWT_SECRET
12. bootstrap admin secret существует и имеет 0600
13. trafficStats API: корректный secret принимает запрос, неверный secret отклоняется
14. TLS mode в config.yaml соответствует runtime env (acme|file|self_signed_dev)
15. при HY2XS_TLS_MODE=acme в config.yaml выставлен acme.type из HY2XS_ACME_TYPE
16. direct hysteria2:// node URL в API/QR формируется по HY2XS_PUBLIC_HOST + HY2XS_PUBLIC_PORT; subscription delivery endpoint отключён в baseline и не входит в acceptance
17. nft -c -f /etc/nftables.conf проходит после apply
18. пароль admin и con_pass не перезаписываются при рестарте hy2xs-admin
19. остановка/рестарт UI не останавливает hysteria-server
20. traffic accounting/kick ориентируются на systemd status, а не на SQLite HYSTERIA2_ENABLE
21. /etc/hysteria/config.yaml имеет 0640 hysteria:hy2xs-admin
22. hy2xs-admin может читать /etc/hysteria/config.yaml, но не может писать

D. Negative tests

1. не Debian 13
2. порт уже занят
3. старое конфликтующее состояние уже существует
4. домен / SNI заданы некорректно
5. bundled UI отсутствует в пакете
6. Hysteria upstream недоступен
7. firewall применился частично
8. install flow прерван посередине
9. попытка использовать HY2XS_IPV6_ENABLED=true
10. HY2XS_PUBLIC_HOST=0.0.0.0

E. Fix20 production matrix (обязательные сценарии)

1. Clean Debian 13 minimal:

   • только SSH, без ручной установки зависимостей;
   • default /etc/nftables.conf stub;
   • install проходит полностью;
   • doctor/status показывают рабочее состояние.

2. Non-systemd container:

   • fail-fast до destructive шагов;
   • диагностическое сообщение с причиной capability/systemd.

3. Foreign nftables:

   • при HY2XS_FIREWALL_MODE=managed install/reconfigure блокируются;
   • при HY2XS_FIREWALL_MODE=takeover создаются backup/rollback guard и apply проходит.

4. Rollback guard cleanup:

   • после успешного apply/smoke не остаются hy2xs-fw-rollback-*.timer/.service.

5. Partial install + repair:

   • состояние install-state фиксирует промежуточную фазу;
   • repair завершает граф до installed=true.

6. AAAA при IPv4-only:

   • policy строго валидируется preflight;
   • soft warning path не используется в production baseline.

7. Slow-start admin readiness:

   • install не падает на race после restart;
   • readiness waiters дожидаются listener/healthz.

Acceptance criteria

Система принимается, если:

1. production builder на Debian 13 amd64 выдаёт переносимый install package
2. target server не выполняет build step
3. Hysteria2 получена из official upstream
4. HY2XS admin поставлен из install package
5. post-install.env отражает фактическое deploy-состояние
6. оркестратор зафиксирован как Bun/TypeScript stack и поставляется как готовый install-артефакт
7. оркестратор не требует standalone update / rollback / uninstall subcommands
8. bounded rollback в install/reconfigure корректно отрабатывает failure-сценарии firewall/systemd/config/smoke
9. Telegram/access layer не требуется для прохождения install acceptance
10. отсутствует production path для port hopping
11. UI не запускается от root
12. клиентские endpoint не зависят от request Host/hostname
13. production build verify падает, если config/hy2xs.env содержит placeholder-значения
14. production build verify падает при dirty git tree (кроме ALLOW_DIRTY_BUILD=true)
15. metadata содержит source_git_commit, dirty_tree, build_profile=production