"""Сверка тестов со сценариями основных спеков `openspec/specs/`.""" import re from collections.abc import Iterable, Mapping from dataclasses import dataclass, field from pathlib import Path import pytest ROOT = Path(__file__).resolve().parents[1] SPECS_DIR = ROOT / "openspec" / "specs" # основные спеки поведения API; спеки контейнера, логов и конфига # проверяются evidence, а не HTTP-тестами CAPABILITIES = ( "api-conventions", "identification", "sessions", "users", "chats", "messages", "pagination", "data-storage", "job-outbox", "chat-cache", "health", "idempotency", "attachments", # уборщик: все сценарии — проверки отказов (design change # upload-consistency, решение 10) "storage-consistency", # с лабы 5 (design change async-attachments, решение 15) "attachment-processing", "message-broker", # с change track1-queue-overload "queue-overload", ) SCENARIO_RE = re.compile(r"^#### Scenario: (.+?)\s*$", re.MULTILINE) type Scenario = tuple[str, str] @dataclass(frozen=True) class Exclusion: """Сценарий, который не воспроизвести по HTTP против сервера.""" reason: str check: str EXCLUDED: dict[Scenario, Exclusion] = { ("api-conventions", "Ответ 500"): Exclusion( reason="500 возникает только при сбое внутри сервиса, " "штатным запросом его не вызвать", check="временно бросить исключение в ручке и запросить её; " "обработчик Exception — src/api/errors.py", ), ("api-conventions", "Исключение внутри обработки"): Exclusion( reason="нужен сбой внутри сервиса, как для «Ответ 500»; " "traceback виден только в логе процесса", check="тот же ручной сбой, затем make logs: запись error с " "traceback и тем же request_id", ), ("api-conventions", "Instance id в ответе 500"): Exclusion( reason="нужен сбой внутри сервиса, как для «Ответ 500»", check="тот же ручной сбой: у ответа 500 есть X-Instance-Id " "процесса; обработчик Exception — src/api/errors.py", ), ("idempotency", "Повтор после рестарта API"): Exclusion( reason="нужен новый процесс API, тесты сервер не трогают", check="отправка с ключом, docker compose up -d --force-recreate " "api, повтор: другой X-Instance-Id, тот же Message — " "evidence/idempotency/replay-after-restart.md", ), ("chat-cache", "Чтение из кэша"): Exclusion( reason="по HTTP ответ из кэша не отличить от ответа из PostgreSQL", check="driver.py --port cache-check скилла " "run-mtusi-messenger: чтения таблицы chats (seq_scan + idx_scan) " "и keyspace_hits Valkey за 50 чтений через LB — " "evidence/cache/hits.md", ), ("chat-cache", "Срок записи"): Exclusion( reason="срок ключа виден только в Valkey", check="driver.py --port cache-check: TTL ключа карточки не " "больше настроенного и чтениями не продлевается — " "evidence/cache/hits.md", ), ("chat-cache", "Временная база"): Exclusion( reason="ключи видны только в Valkey, а набор не знает, на какой " "базе работает", check="make test_isolated, затем driver.py --port " "cache-check --require-test-keys (без ключей тестовой базы — код " "1): число ключей с префиксами рабочей и тестовой базы — " "evidence/cache/hits.md", ), ("data-storage", "Прежний пользователь после рестарта"): Exclusion( reason="нужен рестарт стенда, тесты сервер не трогают", check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: " "прежний токен читает те же данные — " "evidence/replicas/test-persistence.md", ), ("identification", "Кнопка Authorize в Swagger"): Exclusion( reason="это интерфейс /docs в браузере", check="схемы bearerAuth и basicAuth, из которых строится кнопка, " "проверяет тест сценария «Схема в openapi.json»; кнопку — вручную " "(REPORT.md, таблица доказательств)", ), ("sessions", "Токена нет в хранилище"): Exclusion( reason="нужен доступ к таблицам PostgreSQL, а тесты ходят по HTTP", check="driver.py --port auth-storage скилла " "run-mtusi-messenger: token_hash — SHA-256 токена, самого токена " "нет в pg_dump базы — evidence/auth/passwords-and-tokens.md", ), ("sessions", "Прежний токен после рестарта"): Exclusion( reason="нужен рестарт стенда, тесты сервер не трогают", check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — " "evidence/replicas/test-persistence.md", ), ("attachments", "Принявшая реплика остановлена"): Exclusion( reason="нужно остановить реплику API, тесты стенд не трогают", check="driver.py --port attachment-failover [--mode stop|kill] " "скилла run-mtusi-messenger: загрузка через LB, scripts/stop-one.sh " "реплики ответа, скачивание через другую с тем же SHA-256, 404 " "постороннему — evidence/attachments/failover.md", ), ("attachments", "Байты не в БД и не на диске API"): Exclusion( reason="нужен взгляд в схему PostgreSQL, bucket S3 и файловые " "системы контейнеров, а тесты ходят по HTTP", check="driver.py --port attachment-storage: колонки таблиц " "вложений, вид object_key, объект в bucket, анонимный GET — 403, " "docker diff реплик — evidence/attachments/storage.md", ), ("attachments", "Рестарт стенда"): Exclusion( reason="нужен рестарт стенда, тесты сервер не трогают", check="make test-persistence ACTION_SCRIPT=scripts/restart.sh: с " "LAB=4 проверка скачивает тот же оригинал прежним токеном — " "evidence/replicas/test-persistence.md", ), ("attachments", "Одна копия тела при записи в S3"): Exclusion( reason="нужен пик памяти cgroup реплики под одновременными " "загрузками, а тесты ходят по HTTP", check="make bench_uploads (профиль uploads стенда bench/): " "вариант «без лимита» при 10 клиентах по 10 MiB, пик окна над " "памятью до загрузок в телах на загрузку — " "evidence/uploads/baseline/summary.md; у кода до change " "upload-memory — отчёт лабы 4 (mtusi2026lab4-safronov, REPORT.md)", ), ("attachments", "Память не растёт с числом загрузок"): Exclusion( reason="нужен пик памяти cgroup реплики, реплика без swap и " "завершение ядром из-за памяти, а тесты ходят по HTTP", check="make bench_uploads: вариант «с лимитом» при 10, 20 и 40 " "клиентах по 10 MiB — пик окна, oom, ответы по кодам — " "evidence/uploads/baseline/summary.md", ), ("users", "Хэш в БД"): Exclusion( reason="нужен доступ к таблице users, а тесты ходят по HTTP", check="driver.py --port auth-storage: префикс $argon2id$ и " "разные хэши одинаковых паролей, пароля нет в pg_dump базы — " "evidence/auth/passwords-and-tokens.md", ), ("message-broker", "Сервис брокера запущен"): Exclusion( reason="образ, volume и порты контейнера видны только в Docker", check="driver.py --port broker-check: образ с тегом и digest, " "именованный volume, docker port только AMQP на 127.0.0.1 — " "evidence/broker/stand.md", ), ("message-broker", "Предел памяти брокера"): Exclusion( reason="предел памяти виден только в статусе брокера", check="driver.py --port broker-check: предел памяти из " "rabbitmqctl status меньше лимита контейнера — " "evidence/broker/stand.md", ), ("message-broker", "Остановка брокера"): Exclusion( reason="код выхода и время остановки контейнера видны только в " "Docker, а проверка плавной остановки — на рабочем стенде", check="driver.py --port broker-check: docker compose stop " "брокера — код 0 раньше срока — evidence/broker/stand.md", ), ("message-broker", "Очереди разных баз разделены"): Exclusion( reason="прогон на временной базе и взгляд на очереди брокера, а " "набор не знает, на какой базе работает", check="make test_isolated KEEP_TEST_DB=1, driver.py --port " "broker-check --require-test-queue, make test_isolated: очередь " "временной базы есть после первого прогона и нет после второго — " "evidence/broker/isolated.md", ), ("data-storage", "Ограничения обработки в схеме"): Exclusion( reason="нужна прямая вставка в таблицы PostgreSQL, а тесты ходят по " "HTTP", check="driver.py --port attachment-storage: пробы ограничений " "обработки и записи аудита replay в откатываемой транзакции — " "evidence/attachments/storage.md", ), **{ ("queue-overload", scenario): Exclusion( reason=( "нужны открытая нагрузка выше потолка worker, счётчики очереди " "и контрольный поток, а для рестартов — действие над " "контейнером посреди неё: это замер, а не проверка по HTTP" ), check=( f"make bench_queue: {where} — " "evidence/queue/baseline4/summary.md" ), ) for scenario, where in ( ("Работа копится там, где положено", "шкала очереди ячеек"), ("Приём упирается в места загрузки", "блок accept, H9"), ("Сначала места, затем предел", "блок accept, H9"), ("Контрольный поток под перегрузкой", "контрольный поток, H7"), ("Бэклог уходит за измеренное время", "восстановление, H6"), ("Никого не теряем", "обход метаданных, H6"), ("Время до готовности вернулось", "окна before и after, H6"), ("Worker убит под перегрузкой", "блок kill-worker, H8"), ("Брокер перезапущен под перегрузкой", "блок restart-broker, H8"), ) }, } # ссылка исключения на доказательство в репозитории лабы EVIDENCE_RE = re.compile(r"evidence/[\w./-]+\.md") @dataclass class Collected: """Что собрал pytest: маркеры `spec`, модули тестов и сценарии, которые проверяют тесты `fault` (их выполняет только `make failure_checks`).""" marks: dict[Scenario, list[str]] = field(default_factory=dict) modules: set[str] = field(default_factory=set) fault: set[Scenario] = field(default_factory=set) COLLECTED = pytest.StashKey[Collected]() def spec_scenarios(capability: str, specs_dir: Path = SPECS_DIR) -> list[str]: text = (specs_dir / capability / "spec.md").read_text(encoding="utf-8") return SCENARIO_RE.findall(text) def all_scenarios( capabilities: Iterable[str] = CAPABILITIES, specs_dir: Path = SPECS_DIR, ) -> set[Scenario]: return { (capability, scenario) for capability in capabilities for scenario in spec_scenarios(capability, specs_dir) } def coverage_problems( scenarios: set[Scenario], marks: Mapping[Scenario, list[str]], excluded: Mapping[Scenario, Exclusion], ) -> list[str]: """Расхождения между спеками, маркерами и исключениями.""" problems = [ f"no test and no exclusion: {capability} / {scenario}" for capability, scenario in sorted( scenarios - marks.keys() - excluded.keys(), ) ] problems += [ f"marker points to unknown scenario {capability} / {scenario}: " + ", ".join(nodeids) for (capability, scenario), nodeids in sorted(marks.items()) if (capability, scenario) not in scenarios ] problems += [ f"exclusion points to unknown scenario: {capability} / {scenario}" for capability, scenario in sorted(excluded.keys() - scenarios) ] problems += [ f"scenario is both tested and excluded: {capability} / {scenario}" for capability, scenario in sorted(marks.keys() & excluded.keys()) ] return problems def missing_evidence( excluded: Mapping[Scenario, Exclusion], root: Path = ROOT, ) -> list[str]: """Ссылки исключений на файлы `evidence/`, которых нет в репозитории. `evidence/` в следующую лабу не переносится: доказательство снимается заново на её стенде, иначе ссылка повисла бы молча (design change `fix-known-issues`, решение 2).""" return [ f"exclusion refers to missing {path}: {capability} / {scenario}" for (capability, scenario), exclusion in sorted(excluded.items()) for path in EVIDENCE_RE.findall(exclusion.check) if not (root / path).is_file() ]