"""Сверка тестов со сценариями основных спеков `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", "chat-cache", "health", "idempotency", "attachments", # уборщик: все сценарии — проверки отказов (design change # upload-consistency, решение 10) "storage-consistency", ) 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", ), ("users", "Хэш в БД"): Exclusion( reason="нужен доступ к таблице users, а тесты ходят по HTTP", check="driver.py --port auth-storage: префикс $argon2id$ и " "разные хэши одинаковых паролей, пароля нет в pg_dump базы — " "evidence/auth/passwords-and-tokens.md", ), } # ссылка исключения на доказательство в репозитории лабы 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() ]