test: add automatic failure checks on a separate stand

make failure_checks brings up a throwaway compose project with its own
PostgreSQL and Valkey, a default and a tight API (2 s sessions, pool of
one), and runs the pytest tests marked fault through an explicit hook:
session expiry, database stop and return, pool exhaustion, chat creation
rollback, readiness, Valkey stop, hang, return and flush. The stand and
its volume are removed on any outcome; the working stand is untouched.
Regular runs deselect the fault tests, and 13 coverage exclusions go away.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 23:20:34 +03:00
co-authored by Claude Opus 5.5
parent 3e79c6360f
commit 5b65051a60
19 changed files with 1648 additions and 114 deletions
+7
View File
@@ -83,6 +83,13 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша
разделены именем базы. Скрипт запускается `$(PYTHON)`, а не
`uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку.
- `failure_checks: env_setup` — проверки отказов на отдельном стенде,
проект compose `<рабочий>-failures` (`student-tests.md`). От
`start_db` не зависит: стенд свой и удаляется вместе с volume.
`FAULT_ARGS` — аргументы pytest (`make failure_checks FAULT_ARGS='-k
valkey'`). Скрипт тоже запускается `$(PYTHON)`. Все команды docker
проекта отказов — только с `-p <рабочий>-failures`: `down -v` без
него удалил бы рабочий volume.
## Troubleshooting
+36 -9
View File
@@ -46,13 +46,39 @@ paths:
Его вывод — evidence набора против контейнера.
`make student_test` — против любого запущенного стенда (`BASE_URL`),
он оставляет данные в рабочей базе.
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные
Postgres или Valkey), обычный прогон не подходит. Попадание в кэш по
HTTP не отличить от чтения из БД: такие сценарии `chat-cache` —
исключения с evidence. Сами тесты
контейнеры не трогают: стенд готовит явный hook или отдельная цель
Makefile, как `make test-persistence` в skeleton. Механизм выбирает
change `failure-checks`.
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или
замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный
прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль
`test_failures.py`, команда `make failure_checks` (change
`failure-checks`). Попадание в кэш по HTTP не отличить от чтения из
БД: такие сценарии `chat-cache` — исключения с evidence.
- Как устроен `make failure_checks` (`student-tests/run_failures.py`):
- тот же `docker-compose.yml` под проектом `<рабочий>-failures` с
override `failures.compose.yml`: свои Postgres и Valkey со своим
volume, их порты не публикуются;
- два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и
«тесный» (`FAULT_TIGHT_BASE_URL`: срок сессии 2 с, пул 1, короткие
таймауты);
- `pytest -m fault`, затем удаление стенда с volume при любом
исходе. Рабочий стенд не трогается.
- Тесты `fault` сами docker не трогают. На стенд они действуют только
через фикстуру `stand` — hook `student-tests/fault_hook.py`, как
`make test-persistence` вызывает `ACTION_SCRIPT`. Маркер `fault`
выбирает тесты, фикстура `stand` действует на стенд: имена разные
намеренно. Действия: `stop` / `start` /
`pause` / `unpause`, `flush-cache`, `cache-hits`, `cache-has-chat`,
`fail-members` (триггер, который роняет вставку участников),
`count-chats`. Hook работает только с проектом из `FAULT_PROJECT` и
отказывается работать с проектом рабочего стенда.
- Тест `fault`, который останавливает или замораживает хранилище,
делает это в `with outage(...)`: в `finally` хранилище возвращается,
и упавшая проверка не ломает следующие. Границы времени — с запасом
0,3–0,5 с, но на порядок ниже «плохого» поведения (6 с повторов
redis-py, 8 с зависшего запроса).
- `addopts` содержит `-m 'not fault'`: `make student_test` и
`make test_isolated` тесты `fault` собирают (их сценарии видит сверка
покрытия), но не выполняют. Запуск `pytest -m fault` без
`make failure_checks` останавливается до первого теста с кодом 2.
- Пароли и токены тестов синтетические, не печатаются и не попадают в
`evidence/` (`evidence/README.md`).
- `tests/` — публичные проверки skeleton: не править, не ослаблять,
@@ -76,8 +102,9 @@ paths:
- **Каждый тест сценария спека помечен** `@pytest.mark.spec("<capability>",
"<Сценарий>")`, имя — дословно из `#### Scenario:`. Новый сценарий в
основном спеке без теста роняет `test_coverage.py`. Если его нельзя
проверить по HTTP, добавить запись в `EXCLUDED` (`spec_coverage.py`)
с причиной и способом проверки.
проверить по HTTP даже на стенде отказов, добавить запись в
`EXCLUDED` (`spec_coverage.py`) с причиной и способом проверки.
Сценарии тестов `fault` сверка считает покрытыми и печатает их число.
- Модуль сверки называется `spec_coverage.py`, а не `coverage.py`:
каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы
пакет `coverage` (pytest-cov, coverage-runner IDE).
+11 -1
View File
@@ -157,13 +157,23 @@ make run_dev # Postgres + миграции, Valkey, затем 127.0.0.1:8080,
```bash
make check # офлайн-структура skeleton
make test_isolated # образ на временной базе: smoke + student-tests, уборка
make failure_checks # проверки отказов (~45 с) на отдельном стенде <рабочий>-failures
make failure_checks FAULT_ARGS='-k valkey' # только часть проверок отказов
python3 $D all # живой сервер + flow + smoke + student-tests
make lint # ruff; затрагивает и driver.py
```
Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у
`flow`, smoke — `PASS: lab2 public API scenario...`, student — все
прошли, `All checks passed!`; `all` и `test_isolated` — код 0.
прошли (12 тестов `fault` — `deselected`), `All checks passed!`; `all`,
`test_isolated` и `failure_checks` — код 0.
Проверки отказов (`student-tests/test_failures.py`, маркер `fault`)
останавливают и замораживают Postgres и Valkey, поэтому идут только на
своём стенде: `make failure_checks` поднимает проект compose
`<рабочий>-failures` со своими хранилищами и volume и удаляет его после
прогона. Рабочий стенд на 8080 при этом не трогается. `pytest -m fault`
напрямую останавливается с кодом 2: нет hook стенда.
## Gotchas
+10 -13
View File
@@ -81,22 +81,14 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).
Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на
PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change
`session-auth`, кэш Valkey — change `membership-cache`. Этот файл и
`session-auth`, кэш Valkey — change `membership-cache`, автоматические
проверки отказов — change `failure-checks`. Этот файл и
`.claude/rules/` описывают целевое состояние лабы 2, поэтому в
остальном код с ними пока расходится:
- `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с
`X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` —
change `bench-postgres` (`bench.md`);
- сценарии основных спеков, которые выполнятся только после следующих
changes, — внести в их `tasks.md`: в `failure-checks` —
автоматическая проверка «Сбой при добавлении участников», «БД
остановлена», «БД вернулась», «Соединения исчерпаны»
(`data-storage`), «Хранилище не готово», «Кэш недоступен»
(`health`), «Истёкший токен», «Срок не продлевается», «БД
остановлена при запросе с токеном» (`sessions`), «Valkey
остановлен», «Valkey завис», «Valkey вернулся» (`chat-cache`); пока
это исключения в `spec_coverage.py` с ручным evidence;
- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления
базы: иначе в кэше останутся карточки чатов, созданных после снятия
backup (design change `membership-cache`, Risks);
@@ -258,7 +250,8 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` |
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) |
| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом |
| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); сервер недоступен — код 2 и одна строка с адресом |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) |
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
| `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность |
@@ -310,13 +303,17 @@ src/
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
cursor.py # непрозрачный keyset-курсор: кодирование и разбор
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
conftest.py # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat, сбор маркеров spec
conftest.py # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггер сбоя участников (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов
bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick
run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json
k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы
@@ -335,7 +332,7 @@ evidence/storage/ # отказы БД, пул, statement_timeout, р
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md
evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
evidence/profile/<метка>.txt # результаты make bench_inproc
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
+9
View File
@@ -191,6 +191,15 @@ student_test:
test_isolated: env_setup start_db start_cache
$(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,)
# проверки отказов (pytest -m fault) на отдельном стенде: свой проект
# compose <рабочий>-failures со своими Postgres и Valkey, обычный и
# «тесный» API, hook student-tests/fault_hook.py; стенд и его volume
# удаляются при любом исходе, рабочий стенд не затрагивается.
# FAULT_ARGS — дополнительные аргументы pytest, например -k "Valkey"
.PHONY: failure_checks
failure_checks: env_setup
$(PYTHON) student-tests/run_failures.py $(FAULT_ARGS)
.PHONY: lint
lint:
@ruff format .
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-01
+236
View File
@@ -0,0 +1,236 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — дельта спека
`student-tests`.
Что уже есть и на что опираемся:
- `make test_isolated` (`student-tests/run_isolated.py`) поднимает
отдельный контейнер API на временной базе в Postgres рабочего стенда,
гоняет smoke и набор и убирает за собой при любом исходе. Для отказов
он не годится: остановить общий Postgres значит остановить рабочий
стенд.
- Публичная `make test-persistence` (`tests/resilience.py`) сама
запускает исполняемый hook из `ACTION_SCRIPT` — это прецедент «тест
действует на стенд только через явный hook оператора». Правило
`student-tests.md` требует того же и оставляет выбор механизма этому
change.
- Ручные прогоны отказов уже сняты: `evidence/storage/db-unavailable.md`,
`pool-timeout.md`, `evidence/auth/expiry.md`, `evidence/cache/outage.md`,
`flush-restart.md`. Значения (503 за 0,01 с при остановленной БД,
пул 1 и `pool_timeout` 1 с → 503 за 1 с, Valkey на паузе — +0,2 с)
дают границы для проверок.
- Проверено на Compose v5.5.1: `docker compose -p mtusi-lab2-failures -f
docker-compose.yml -f <override>` даёт отдельный volume
`mtusi-lab2-failures_postgres_data` и сеть, а `ports: !reset []` в
override снимает публикацию портов.
- Ошибка из триггера PostgreSQL (`RAISE EXCEPTION`, SQLSTATE `P0001`) не
входит в классы недоступности `src/infra/db/errors.py`, поэтому API
ответит 500 `internal_error`, а не 503.
- pytest: свой `pytest_collection_modifyitems` в `conftest.py` помечен
`tryfirst` и собирает маркеры `spec` до отбора по `-m` (у плагина меток
pytest хук без `tryfirst`). Значит, тесты, исключённые из прогона
через `-m "not fault"`, сверка покрытия всё равно видит.
## Goals / Non-Goals
**Goals:**
- Одна команда без ручных шагов, которая проверяет все сценарии отказов
и оставляет хост в исходном состоянии.
- Рабочий стенд не меняется ни на секунду: ни рестарта, ни паузы, ни
чужих данных в его базе и кэше.
- Проверки устойчивы к скорости хоста: границы времени с запасом, но
ловят порядок величины (0,2 с против 6 с).
**Non-Goals:**
- Изменения кода приложения: проверяется готовое поведение.
- Отказ API-реплики и балансировщика — лаба 3 (`make test-failover`).
- Сценарии, которым нужен рестарт стенда («Прежний токен после
рестарта» — это `make test-persistence`), доступ к таблицам
(«Токена нет в хранилище», «Хэш в БД») или браузер: они остаются
исключениями с evidence.
- Запуск проверок отказов в CI skeleton: CI приложение не запускает.
## Decisions
### 1. Отдельный проект compose `mtusi-lab2-failures`
Стенд отказов — тот же `docker-compose.yml` (те же пины, healthcheck,
конфиг Valkey, якорь окружения), запущенный под другим именем проекта и
с override `student-tests/failures.compose.yml`:
```yaml
services:
postgres: { ports: !reset [] }
valkey: { ports: !reset [] }
api: { ports: !reset [] }
```
Свой volume, своя сеть, порты Postgres и Valkey не публикуются: с хоста к
ним ходит только hook через `docker compose exec`. Сервис `api` проекта
не запускается — контейнеры API создаёт оркестратор (решение 2).
*Альтернативы:*
- Проверки на рабочем стенде: останавливают рабочую БД и кэш, смешивают
тестовые данные с рабочими. Отвергнута.
- Временная база в рабочем Postgres, как у `test_isolated`: остановить
или заморозить можно только весь сервер. Отвергнута.
### 2. Два контейнера API: обычный и «тесный»
Оркестратор поднимает их как `run_isolated.py`: `docker compose run -d
--no-deps --name … -p 127.0.0.1:<порт>:${APP__PORT} -e … api`. Порты
хоста — свободные, их выбирает оркестратор (bind на `127.0.0.1:0`):
новых переменных в `.env` не нужно.
| API | Окружение | Для сценариев |
|---|---|---|
| обычный | настройки по умолчанию (срок сессии 3600 с, пул 10 + 5) | отказы БД и Valkey, readiness, откат, очистка кэша |
| тесный | `AUTH__SESSION_TTL_SECONDS=2`, `DATABASE__POOL_SIZE=1`, `DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`, `DATABASE__REQUEST_TIMEOUT_SECONDS=2` | истечение сессии, исчерпание пула |
Обычный нужен отдельно: «БД остановлена при запросе с токеном» требует,
чтобы после возврата БД *тот же* токен получил 200, а со сроком 2 с он
истёк бы раньше. Срок и пул в одном тесном контейнере не мешают друг
другу: эти тесты короткие и идут по очереди. Короткий срок запроса
(2 с) сокращает тест пула: первый запрос освобождает соединение через
2 + 2 с, а не через 6 + 2 с.
*Альтернатива:* три контейнера (срок, пул, обычный). Отвергнута: лишний
контейнер без выигрыша в ясности проверок.
### 3. Hook `student-tests/fault_hook.py`
Исполняемый stdlib-скрипт. Тест вызывает его как `[FAULT_HOOK, действие,
аргументы…]` без shell, как `resilience.py` вызывает `ACTION_SCRIPT`.
Hook работает только с проектом из переменной `FAULT_PROJECT`. Если её
нет или она совпадает с проектом рабочего стенда, hook отказывается
работать (код 2). Каждый вызов — команда `docker compose -p
$FAULT_PROJECT -f docker-compose.yml -f student-tests/failures.compose.yml`.
| Действие | Что делает | Вывод |
|---|---|---|
| `stop` / `start` `postgres`\|`valkey` | `stop`; `start` + `up -d --wait` (ждёт healthcheck) | — |
| `pause` / `unpause` `postgres`\|`valkey` | заморозка; разморозка + ожидание ответа сервиса той же проверкой, что в healthcheck (`pg_isready`, `PING`). Статус Docker после `unpause` до следующего запуска healthcheck (до 5 с) остаётся `unhealthy`, и `up --wait` сразу выходит с ошибкой — найдено на первом прогоне | — |
| `flush-cache` | `FLUSHALL` | — |
| `cache-hits` | `keyspace_hits` из `INFO stats` | число |
| `cache-has-chat <id>` | `EXISTS` ключа карточки (`messenger:v1:<db>:chat:<id>`) | `0` / `1` |
| `fail-members <title>` | триггер `BEFORE INSERT ON chat_members`: `RAISE EXCEPTION`, если у чата это название | — |
| `clear-fail-members` | удаляет триггер и функцию | — |
| `count-chats <title>` | `count(*)` из `chats` по названию | число |
Пароль Valkey hook не видит и не печатает: `valkey-cli` в контейнере
берёт его из `VALKEYCLI_AUTH`. psql — от `POSTGRES_USER` контейнера.
*Альтернатива:* тесты сами вызывают `docker compose`. Отвергнута: тест
тогда знает про docker и может задеть рабочий стенд; правило
`student-tests.md` и спек это запрещают.
*Альтернатива для отката:* заморозить БД между двумя вставками.
Отвергнута: окна нет, вставки идут подряд за миллисекунды. Триггер в
базе стенда отказов даёт сбой ровно на второй вставке; база после
прогона удаляется вместе со стендом, миграций он не касается.
### 4. Тесты: `student-tests/test_failures.py`, маркер `fault`
- Маркер `fault` объявлен в `pyproject.toml`. В `addopts` добавлено
`-m "not fault"`: `make student_test` и `make test_isolated` эти тесты
собирают, но не выполняют. Оркестратор запускает `pytest -m fault`:
последний `-m` перекрывает `addopts`.
- Фикстуры в `conftest.py`: `stand` (вызов hook, возвращает stdout:
`stand("stop", "postgres")`), `tight_api` (`Api` на
`FAULT_TIGHT_BASE_URL`). Фикстура названа не `fault`, чтобы не
путаться с маркером: маркер выбирает тесты, фикстура действует на
стенд. Если `FAULT_HOOK` не задан, а выбран хотя бы один тест `fault`,
— `pytest.exit` в `pytest_collection_finish` с текстом «run make
failure_checks» и кодом 2, до первого теста: ни одно хранилище не
трогается (спек, «Проверка отказа без hook»).
- Каждый тест, который останавливает или замораживает хранилище, делает
это в контекстном менеджере, который в `finally` запускает и
размораживает его обратно. Упавшая проверка не оставляет стенд
сломанным для следующих.
- Границы времени (запас на планировщик Docker Desktop):
| Сценарий | Проверка |
|---|---|
| «БД остановлена» | 503 `unavailable`, `message` — общий текст, ответ < 2 с |
| «Хранилище не готово» | `/health/ready` 503 < 2,5 с, `/health/live` 200 |
| «Соединения исчерпаны» | второй запрос — 503 < 1 + 0,5 с, пока первый держит соединение |
| «Valkey завис» | первый запрос не дольше медианы до паузы + 0,2 + 0,3 с |
| «Valkey остановлен» | 200 / 201 / 200, тела как с кэшем, < 0,2 + 0,3 с |
| «Valkey вернулся» | после `start` и 5,5 с — `cache-hits` растёт при чтении карточки |
| «Истёкший токен», «Срок не продлевается» | тесный API, 401 с вызовом Bearer к 3 с после входа |
- Сценарий «Сбой при добавлении участников»: `fail-members <уникальное
название>`, `POST /chats` → 500 `internal_error`, чата с этим названием
нет в списках обоих участников и `count-chats` = 0; в `finally` —
`clear-fail-members`.
### 5. Оркестратор `student-tests/run_failures.py` и цель Makefile
По образцу `run_isolated.py`, только stdlib, запускается `$(PYTHON)`:
1. Имя проекта — `<проект рабочего стенда>-failures`. Перед стартом
проверка: имя не совпадает с рабочим, иначе выход с кодом 2.
2. Уборка хвоста: `down -v --remove-orphans` проекта отказов и `docker
rm -f` контейнеров API по именам.
3. `docker compose build api` — образ из рабочего дерева (тот же тег, что
у `test_isolated`; работающий рабочий контейнер это не затрагивает).
4. `up -d --wait postgres valkey`, `run --rm migrate`, два `run -d` API,
ожидание `/health/ready` каждого.
5. `uv run pytest -m fault` с окружением `BASE_URL`,
`FAULT_TIGHT_BASE_URL`, `FAULT_HOOK`, `FAULT_PROJECT`.
6. При провале — хвосты журналов обоих API. В `finally` — уборка как в
шаге 2, повторный Ctrl+C игнорируется.
`Makefile`: `failure_checks: env_setup` → `$(PYTHON)
student-tests/run_failures.py`. От `start_db` цель не зависит: стенд
свой.
### 6. Сверка покрытия
13 записей `EXCLUDED` удаляются: их сценарии получают тесты с маркерами
`spec` и `fault`. `Collected` дополнительно запоминает сценарии, чьи
тесты помечены `fault`. Итог сверки становится таким: «coverage: N
scenarios in M specs, T tested (F by make failure_checks), E excluded».
### 7. Evidence
`evidence/tests/failure-checks.md`: команда, дата, commit, стенд,
вывод прогона с длительностями, список проверенных сценариев.
Доказательство, что рабочий стенд не тронут: `StartedAt` его контейнеров
до и после и число строк в его таблицах.
## Risks / Trade-offs
- [`down -v` в уборке удаляет volume — ошибка в имени проекта стёрла бы
рабочие данные] → Имя проекта — константа с суффиксом `-failures`.
Оркестратор и hook сверяют его с проектом рабочего стенда и
отказываются работать при совпадении. Команды без `-p` не вызываются.
- [Проверки времени нестабильны на медленном хосте] → Запас 0,3–0,5 с
к границам, которые отличаются от «плохого» поведения на порядок (6 с
повторов redis-py, 8 с зависшего запроса). В выводе — фактические
длительности.
- [Прогон дольше `test_isolated`: свой Postgres с initdb, окна пропуска
кэша по 5 с, срок сессии 2–3 с] → Около 2 минут. Это отдельная цель,
в обычный прогон она не входит.
- [`make student_test` больше не выполняет часть тестов набора] → Вывод
pytest показывает их как `deselected`. Сверка покрытия печатает,
сколько сценариев покрыто через `make failure_checks`. `REPORT.md` и
правило называют обе команды.
- [Сбой отката вызван триггером, а не реальной ошибкой БД] → Проверяется
свойство транзакции, а не причина сбоя: любая ошибка второй вставки
должна откатить первую. Ответ 500 — честный исход внутреннего сбоя.
- [Образ `mtusi-messenger:lab2` пересобирается, как и в `test_isolated`]
→ Уже работающий рабочий контейнер держит прежний образ.
`make run_docker` его и так пересобирает.
## Migration Plan
Порядок: override и hook → оркестратор и цель Makefile → тесты и
фикстуры → маркер и сверка покрытия → прогон `make failure_checks` и
`make test_isolated` → документы → commit → evidence → `REPORT.md` →
commit. Откат — `git revert`: приложение и рабочий стенд не меняются.
@@ -0,0 +1,94 @@
# Proposal
## Why
Уровень «4» требует автоматическую проверку истечения сессии при коротком
`SESSION_TTL_SECONDS` и недоступности Redis/Valkey и БД: при потере
сервиса приложение отвечает ограниченной ошибкой или обходит кэш и не
принимает анонимный запрос (`README.md`). Сейчас эти сценарии проверены
только вручную. В `spec_coverage.py` это 13 исключений со ссылками на
evidence: истечение сессии, остановленная и зависшая БД, исчерпанный
пул, откат создания чата, отказы Valkey, readiness. Обычный прогон их
выполнить не может: ему нужны особый стенд и действия над хранилищами,
а набор `student-tests` по правилу сам стенд не трогает.
## What Changes
- Новая цель `make failure_checks` поднимает **отдельный стенд отказов**:
- свой проект compose `mtusi-lab2-failures` со своими PostgreSQL и
Valkey, без публикации их портов;
- образ из рабочего дерева и миграции;
- два контейнера API: с настройками по умолчанию и «тесный» — срок
сессии 2 с, пул из одного соединения, короткие таймауты.
Затем цель прогоняет проверки отказов и удаляет стенд вместе с его
volume при любом исходе. Рабочий стенд, его база и кэш не
затрагиваются.
- Проверки отказов — тесты `student-tests` с маркером `fault`. На стенд
они действуют только через явный hook, который им передаёт
`make failure_checks`, как `make test-persistence` передаёт
`ACTION_SCRIPT`. Hook умеет:
- останавливать, запускать, замораживать и размораживать Postgres и
Valkey;
- очищать кэш;
- включать сбой записи участников (триггер в базе стенда отказов);
- отвечать на вопросы о состоянии: есть ли чат с названием, есть ли
ключ карточки, сколько попаданий в кэш.
Код приложения и docker тесты сами не трогают.
- `make student_test` и `make test_isolated` проверки отказов не
запускают: маркер `fault` исключён из обычного прогона. Его сценарии
при этом считаются покрытыми, и сверка покрытия по-прежнему видит
все сценарии.
- Автоматическими становятся 13 сценариев:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД
остановлена при запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey
вернулся», «Очистка кэша».
Их записи в `EXCLUDED` удаляются. Исключениями остаются сценарии,
которым нужен не отказ, а рестарт стенда, доступ к таблицам или
браузер.
- Поведение приложения не меняется: проверяется то, что уже
реализовано.
Вне этого change: нагрузочный стенд и EXPLAIN (`bench-postgres`), трек 2,
отказ API-реплики (лаба 3, `make test-failover`).
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `student-tests`:
- новое требование — проверки отказов на отдельном стенде
(`make failure_checks`);
- «Только по HTTP» — действие на стенд только через переданный hook;
- «Запуск одной командой» — набор без проверок отказов;
- «Покрытие сценариев основных спеков» — сценарий, покрытый
проверкой отказа, считается покрытым;
- «Результат прогона сохраняется» — и вывод `make failure_checks`.
## Impact
- Тесты: `student-tests/test_failures.py` (маркер `fault`), фикстуры
hook и тесного API в `conftest.py`, `api_client.py` при необходимости;
`spec_coverage.py` — удаление 13 исключений; итог сверки покрытия
называет число сценариев, покрытых проверками отказов.
- Инструменты: `student-tests/run_failures.py` (оркестратор, stdlib),
`student-tests/fault_hook.py` (hook, stdlib, исполняемый),
`student-tests/failures.compose.yml` (override: без публикации
портов); `Makefile` — цель `failure_checks`; `pyproject.toml` —
маркер `fault` и его исключение из обычного прогона.
- Код приложения, контракт и compose рабочего стенда не меняются.
- Документы: правила `student-tests.md`, `run-modes.md`; `AGENTS.md`
(команды, карта кода, «Переходное состояние» — пункт про
`failure-checks` закрывается); скилл; `REPORT.md` — строки уровня «4»
про автоматические проверки и `make failure_checks` в «Проверках»;
`evidence/tests/failure-checks.md`.
@@ -0,0 +1,145 @@
# Spec Delta
## ADDED Requirements
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- сессии: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша».
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL и Valkey, применить
миграции;
- запустить API с настройками по умолчанию и API с коротким сроком
сессии и пулом из одного соединения;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Порты PostgreSQL и Valkey этого стенда MUST NOT публиковаться на хосте,
API — только на `127.0.0.1`. Рабочий стенд, его база, кэш и контейнеры
MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла
хотя бы одна проверка или уборка.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volume стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
- **THEN** код выхода ненулевой, журналы API стенда отказов выведены,
стенд отказов удалён
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volume
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volume стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
## MODIFIED Requirements
### Requirement: Запуск одной командой
Набор, кроме проверок отказов (требование «Проверки отказов на
отдельном стенде»), SHALL запускаться одной командой `make student_test`
против сервера по адресу `BASE_URL`, по умолчанию
`http://localhost:8080`. Команда SHALL завершаться с кодом 0, только
если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор
MUST завершаться с ненулевым кодом и сообщением о недоступности адреса,
а не множеством ошибок отдельных тестов.
#### Scenario: Все тесты прошли
- **WHEN** сервер запущен и `make student_test` выполняется без
аргументов
- **THEN** все тесты, кроме проверок отказов, проходят, команда
завершается с кодом 0, а проверки отказов в прогоне не выполняются
#### Scenario: Другой адрес
- **WHEN** выполняется `make student_test BASE_URL=http://localhost:8090`
- **THEN** тесты обращаются к `http://localhost:8090`
#### Scenario: Сервер не запущен
- **WHEN** по `BASE_URL` никто не слушает
- **THEN** команда завершается с ненулевым кодом, а вывод называет
недоступный адрес
### Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Проверки отказов
SHALL действовать на хранилища стенда и узнавать их состояние только
через hook, который им передаёт `make failure_checks`. Без hook они
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
запущенного на хосте, и против контейнера.
#### Scenario: Консоль и контейнер
- **WHEN** набор запускается сначала против `make run_dev`, затем против
`make run_docker`
- **THEN** оба прогона проходят одинаково
#### Scenario: Проверка отказа без hook
- **WHEN** проверки отказов запущены pytest напрямую, без
`make failure_checks`
- **THEN** они завершаются ошибкой, которая называет `make
failure_checks`, и ни одно хранилище не останавливается
### Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache` и `health`, который
воспроизводится по HTTP против работающего сервера, в том числе на
стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть
понятно, какой capability и сценарий он проверяет. Сценарий, который
проверяет тест отказа, SHALL считаться покрытым, хотя `make
student_test` этот тест не выполняет; итог сверки SHALL называть, сколько
сценариев покрыто проверками отказов. Сценарии, которые по HTTP не
воспроизвести, SHALL быть перечислены с причиной и способом проверки.
#### Scenario: Сверка покрытия
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера (`make test_isolated`) и вывод `make
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и
автоматические проверки истечения сессии и недоступности БД и Valkey.
#### Scenario: Доказательство в отчёте
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
вывода в `evidence/`
+90
View File
@@ -0,0 +1,90 @@
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельта `specs/student-tests/spec.md`. Перед первым файлом слоя прочитать
его правило: `student-tests.md`, `run-modes.md`, `docker.md`. Evidence
снимается с закоммиченного кода, коммит — только после подтверждения
пользователя (`bench.md`, «Измеренное состояние — commit»).
## 1. Стенд отказов и hook
- [x] 1.1 `student-tests/failures.compose.yml` — override без публикации
портов `postgres`, `valkey`, `api` (решение 1). Проверка: `docker
compose -p mtusi-lab2-failures -f docker-compose.yml -f
student-tests/failures.compose.yml config` — у сервисов нет `ports`,
volume `mtusi-lab2-failures_postgres_data`.
- [x] 1.2 `student-tests/fault_hook.py` — действия из таблицы решения 3,
отказ без `FAULT_PROJECT` и при совпадении с рабочим проектом,
исполняемый бит. Проверка: без `FAULT_PROJECT` и с
`FAULT_PROJECT=mtusi-lab2` — код 2 и ни одной команды docker; на
поднятом вручную проекте отказов каждое действие отрабатывает
(`stop`/`start`, `pause`/`unpause`, `cache-hits`, `fail-members` →
вставка участников падает, `clear-fail-members` → проходит).
- [x] 1.3 `student-tests/run_failures.py` и цель `failure_checks` в
`Makefile` (решения 2, 5): уборка хвоста, сборка, стенд, миграции,
два API на свободных портах, `pytest -m fault`, журналы при провале,
уборка в `finally`, защита от имени рабочего проекта. Проверка: `make
-n failure_checks`; прогон с пустым набором (`-k nothing`) — стенд
поднимается и удаляется, `docker volume ls` без
`mtusi-lab2-failures_*`; Ctrl+C во время прогона — уборка доходит до
конца.
## 2. Проверки отказов
- [x] 2.1 Маркер `fault` в `pyproject.toml`, `-m "not fault"` в
`addopts`; фикстуры `stand` и `tight_api`, остановка прогона без
`FAULT_HOOK` (решение 4). Проверка: `uv run pytest -m fault` без
оркестратора — код 2 и текст про `make failure_checks`; `make
student_test` — тесты `fault` в `deselected`.
- [x] 2.2 `student-tests/test_failures.py`: сценарии `sessions`
(«Истёкший токен», «Срок не продлевается», «БД остановлена при запросе
с токеном») и `data-storage` («Сбой при добавлении участников», «БД
остановлена», «БД вернулась», «Соединения исчерпаны»), маркеры `spec`
и `fault`, восстановление хранилища в `finally`. Проверка: `make
failure_checks` — проверки проходят. Временная порча приложения
(например, 500 вместо 503 в `get_db_session`) роняет «БД остановлена»
и не попадает в коммит.
- [x] 2.3 Сценарии `health` («Хранилище не готово», «Кэш недоступен») и
`chat-cache` («Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша») с границами времени из решения 4. Проверка: `make
failure_checks` — проходят. Временный клиент с повторами redis-py по
умолчанию роняет «Valkey завис» и в коммит не попадает.
- [x] 2.4 Сверка покрытия (решение 6): 13 записей `EXCLUDED` удалены,
`Collected` различает тесты `fault`, итог печатает их число.
Проверка: `make student_test` — `test_coverage.py` проходит, строка
`coverage:` называет число сценариев через `make failure_checks`;
`openspec validate --specs`.
## 3. Документы и проверка кода
- [x] 3.1 `/opsx:sync` дельты `student-tests`. Правила:
`student-tests.md` (выбранный механизм, hook, маркер `fault`),
`run-modes.md` (цель `failure_checks`); `AGENTS.md` — команды, карта
кода, «Переходное состояние» без пункта про `failure-checks`; скилл —
`make failure_checks` в разделе Test. Проверка: `grep -rn
"failure-checks" AGENTS.md .claude` — нет обещаний на будущее, только
описание сделанного.
- [x] 3.2 Финальная проверка: `make lint`, `make check`, `openspec
validate failure-checks --strict`, `make test_isolated` — код 0 (тесты
`fault` в нём не выполняются), `make failure_checks` — код 0, рабочий
стенд не перезапускался (`StartedAt`). Затем показать изменения,
предложить сообщение и после подтверждения закоммитить.
## 4. Evidence и отчёт
- [ ] 4.1 `evidence/tests/failure-checks.md` с закоммиченного кода
(решение 7). Проверка: в файле дата, commit, стенд, длительности
проверок, `StartedAt` рабочих контейнеров до и после; паролей и
токенов нет.
- [ ] 4.2 `REPORT.md`:
- `make failure_checks` в «Проверках» и «Сценарии защиты»;
- строки уровня «4» про автоматические проверки истечения сессии и
недоступности БД и Valkey, про атомарность создания чата (вместо
TODO) — со ссылкой на evidence;
- «Остальные пункты уровня 4» — только EXPLAIN.
Проверка: у каждой строки таблицы доказательств есть команда,
наблюдение и файл.
- [ ] 4.3 `make lint`, `make check`, `openspec validate failure-checks
--strict`, `graphify update .`; показать изменения и после
подтверждения закоммитить evidence и отчёт.
+90 -18
View File
@@ -11,18 +11,20 @@
### Requirement: Запуск одной командой
Весь набор SHALL запускаться одной командой `make student_test` против
сервера по адресу `BASE_URL`, по умолчанию `http://localhost:8080`.
Команда SHALL завершаться с кодом 0, только если прошли все тесты. Если
сервер по `BASE_URL` не отвечает, набор MUST завершаться с ненулевым
кодом и сообщением о недоступности адреса, а не множеством ошибок
отдельных тестов.
Набор, кроме проверок отказов (требование «Проверки отказов на
отдельном стенде»), SHALL запускаться одной командой `make student_test`
против сервера по адресу `BASE_URL`, по умолчанию
`http://localhost:8080`. Команда SHALL завершаться с кодом 0, только
если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор
MUST завершаться с ненулевым кодом и сообщением о недоступности адреса,
а не множеством ошибок отдельных тестов.
#### Scenario: Все тесты прошли
- **WHEN** сервер запущен и `make student_test` выполняется без
аргументов
- **THEN** все тесты проходят, команда завершается с кодом 0
- **THEN** все тесты, кроме проверок отказов, проходят, команда
завершается с кодом 0, а проверки отказов в прогоне не выполняются
#### Scenario: Другой адрес
@@ -38,9 +40,12 @@
### Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Один и тот же набор
SHALL проходить против сервера, запущенного на хосте, и против
контейнера.
код приложения, запускать или останавливать сервер. Проверки отказов
SHALL действовать на хранилища стенда и узнавать их состояние только
через hook, который им передаёт `make failure_checks`. Без hook они
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
запущенного на хосте, и против контейнера.
#### Scenario: Консоль и контейнер
@@ -48,6 +53,13 @@ SHALL проходить против сервера, запущенного н
`make run_docker`
- **THEN** оба прогона проходят одинаково
#### Scenario: Проверка отказа без hook
- **WHEN** проверки отказов запущены pytest напрямую, без
`make failure_checks`
- **THEN** они завершаются ошибкой, которая называет `make
failure_checks`, и ни одно хранилище не останавливается
### Requirement: Независимость прогонов
Каждый тест SHALL создавать собственных пользователей с уникальным
@@ -136,10 +148,13 @@ SHALL проходить против сервера, запущенного н
Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache` и `health`, который
воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из
имени или описания теста SHALL быть понятно, какой capability и
сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести,
SHALL быть перечислены с причиной и способом проверки.
воспроизводится по HTTP против работающего сервера, в том числе на
стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть
понятно, какой capability и сценарий он проверяет. Сценарий, который
проверяет тест отказа, SHALL считаться покрытым, хотя `make
student_test` этот тест не выполняет; итог сверки SHALL называть, сколько
сценариев покрыто проверками отказов. Сценарии, которые по HTTP не
воспроизвести, SHALL быть перечислены с причиной и способом проверки.
#### Scenario: Сверка покрытия
@@ -147,6 +162,12 @@ SHALL быть перечислены с причиной и способом п
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Проверка формы ответов
Тесты SHALL проверять не только статус.
@@ -163,10 +184,11 @@ SHALL быть перечислены с причиной и способом п
### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера SHALL сохраняться в `evidence/` с
командой, датой, commit, адресом стенда и итогом. `REPORT.md` SHALL
ссылаться на него в строках уровня «4»: собственные тесты и 100
сообщений от 10 клиентов.
Вывод прогона против контейнера (`make test_isolated`) и вывод `make
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и
автоматические проверки истечения сессии и недоступности БД и Valkey.
#### Scenario: Доказательство в отчёте
@@ -222,3 +244,53 @@ MUST NOT затрагиваться, а карточки чатов тестов
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- сессии: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша».
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL и Valkey, применить
миграции;
- запустить API с настройками по умолчанию и API с коротким сроком
сессии и пулом из одного соединения;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Порты PostgreSQL и Valkey этого стенда MUST NOT публиковаться на хосте,
API — только на `127.0.0.1`. Рабочий стенд, его база, кэш и контейнеры
MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла
хотя бы одна проверка или уборка.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volume стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
- **THEN** код выхода ненулевой, журналы API стенда отказов выведены,
стенд отказов удалён
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volume
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volume стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
+4 -1
View File
@@ -69,9 +69,12 @@ dev = [
testpaths = ["student-tests"]
# каталог с дефисом не пакет: хелперы импортируются как модули
pythonpath = ["student-tests"]
addopts = "-v -rP --strict-markers"
# проверки отказов (маркер fault) — только make failure_checks: там
# pytest -m fault перекрывает этот -m
addopts = "-v -rP --strict-markers -m 'not fault'"
markers = [
"spec(capability, scenario): сценарий основного спека, который проверяет тест",
"fault: проверка отказа хранилища; нужен стенд make failure_checks и его hook",
]
[tool.hatch.build.targets.wheel]
+60 -1
View File
@@ -1,7 +1,8 @@
"""Настройка набора: адрес стенда, проверка доступности, фикстуры."""
import os
from collections.abc import Iterator
import subprocess
from collections.abc import Callable, Iterator
from typing import Any
import httpx
@@ -11,6 +12,10 @@ from api_client import Actor, Api
from spec_coverage import COLLECTED, Collected
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/")
# hook стенда отказов и «тесный» API задаёт make failure_checks
FAULT_HOOK = os.environ.get("FAULT_HOOK", "")
FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/")
FAULT_HOOK_TIMEOUT_S = 120
@pytest.hookimpl(tryfirst=True)
@@ -22,15 +27,35 @@ def pytest_collection_modifyitems(
collected = Collected()
for item in items:
collected.modules.add(item.path.name)
is_fault = item.get_closest_marker("fault") is not None
for mark in item.iter_markers("spec"):
if len(mark.args) != 2 or mark.kwargs:
raise pytest.UsageError(
f"{item.nodeid}: spec marker takes (capability, scenario)",
)
collected.marks.setdefault(mark.args, []).append(item.nodeid)
if is_fault:
collected.fault.add(mark.args)
config.stash[COLLECTED] = collected
@pytest.hookimpl(trylast=True)
def pytest_collection_finish(session: pytest.Session) -> None:
"""Проверки отказов без стенда make failure_checks не запускаются.
Выход до первого теста: без hook ни одно хранилище не трогается.
"""
selected = [
item for item in session.items if item.get_closest_marker("fault")
]
if selected and not (FAULT_HOOK and FAULT_TIGHT_BASE_URL):
pytest.exit(
"fault checks need the failure stand and its hook: "
"run make failure_checks",
returncode=2,
)
@pytest.fixture(scope="session", autouse=True)
def _server_reachable() -> None:
"""Без сервера прогон останавливается одной строкой, а не 100 ошибками."""
@@ -80,3 +105,37 @@ def eve(api: Api) -> Actor:
def chat(api: Api, alice: Actor, bob: Actor) -> dict[str, Any]:
"""Чат Алисы и Боба."""
return api.create_chat(alice, bob, title="Алиса и Боб")
@pytest.fixture(scope="session")
def stand() -> Callable[..., str]:
"""Действие над стендом отказов через hook; возвращает его stdout.
`stand("stop", "postgres")` — «стенд, останови postgres». Hook —
исполняемый файл, вызов без shell, как `ACTION_SCRIPT` в
`tests/resilience.py`. Сам тест docker не трогает. Не путать с
маркером `fault`: он только выбирает тесты (`-m fault`).
"""
def call(*args: str) -> str:
result = subprocess.run(
[FAULT_HOOK, *args],
capture_output=True,
text=True,
timeout=FAULT_HOOK_TIMEOUT_S,
check=False,
)
assert result.returncode == 0, (
f"fault hook {' '.join(args)}: {result.stderr.strip()}"
)
return result.stdout.strip()
return call
@pytest.fixture(scope="session")
def tight_api() -> Iterator[Api]:
"""API стенда отказов со сроком сессии 2 с и пулом из одного
соединения."""
with Api(FAULT_TIGHT_BASE_URL) as client:
yield client
+12
View File
@@ -0,0 +1,12 @@
# Override стенда отказов make failure_checks (student-tests/run_failures.py):
# тот же docker-compose.yml под проектом mtusi-lab2-failures, со своим
# volume и сетью. Порты Postgres и Valkey не публикуются: к ним ходит только
# fault_hook.py через docker compose exec. Сервис api не запускается,
# контейнеры API создаёт оркестратор (docker compose run -p 127.0.0.1:...).
services:
postgres:
ports: !reset []
valkey:
ports: !reset []
api:
ports: !reset []
+249
View File
@@ -0,0 +1,249 @@
#!/usr/bin/env python3
"""Hook стенда отказов для проверок `fault` (`make failure_checks`).
Тесты вызывают его как `[FAULT_HOOK, действие, аргументы…]` без shell —
так же `tests/resilience.py` вызывает `ACTION_SCRIPT`. Сами тесты docker
не трогают. Hook работает только с проектом compose из `FAULT_PROJECT`,
его задаёт `student-tests/run_failures.py`. Проект рабочего стенда hook
не трогает. Решение 3 design change `failure-checks`.
Действия:
stop|start|pause|unpause postgres|valkey
flush-cache FLUSHALL
cache-hits keyspace_hits из INFO stats
cache-has-chat <chat_id> EXISTS ключа карточки: 0 или 1
fail-members <title> вставка участников чата с этим названием
падает (триггер в базе стенда отказов)
clear-fail-members убрать триггер
count-chats <title> число чатов с этим названием
Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH
контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib.
"""
from __future__ import annotations
import json
import os
import subprocess
import sys
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
COMPOSE_FILES = (
ROOT / "docker-compose.yml",
ROOT / "student-tests" / "failures.compose.yml",
)
PROJECT_SUFFIX = "-failures"
SERVICES = ("postgres", "valkey")
# та же проверка, что в healthcheck сервиса в docker-compose.yml
PROBES = {
"postgres": 'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" '
'-d "$POSTGRES_DB"',
"valkey": 'test "$(valkey-cli -p "$VALKEY_PORT" ping)" = PONG',
}
PROBE_TIMEOUT_S = 30
# начало ключа карточки — как CACHE_KEY_PREFIX приложения
CACHE_KEY_PREFIX = "messenger:v1"
FAIL_MEMBERS_SQL = """\
CREATE OR REPLACE FUNCTION fault_fail_members() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF (SELECT title FROM chats WHERE id = NEW.chat_id) = TG_ARGV[0] THEN
RAISE EXCEPTION 'fault injected: chat members insert';
END IF;
RETURN NEW;
END
$$;
DROP TRIGGER IF EXISTS fault_fail_members ON chat_members;
CREATE TRIGGER fault_fail_members BEFORE INSERT ON chat_members
FOR EACH ROW EXECUTE FUNCTION fault_fail_members(:'title');
"""
CLEAR_FAIL_MEMBERS_SQL = """\
DROP TRIGGER IF EXISTS fault_fail_members ON chat_members;
DROP FUNCTION IF EXISTS fault_fail_members();
"""
COUNT_CHATS_SQL = "SELECT count(*) FROM chats WHERE title = :'title';\n"
class HookError(Exception):
"""Неверный вызов или проект: код 2 и сообщение в stderr."""
def working_project() -> str:
"""Имя проекта рабочего стенда — из docker-compose.yml без `-p`."""
result = subprocess.run(
["docker", "compose", "config", "--format", "json"],
cwd=ROOT,
text=True,
capture_output=True,
check=True,
)
return json.loads(result.stdout)["name"]
def fault_project() -> str:
project = os.environ.get("FAULT_PROJECT", "")
if not project.endswith(PROJECT_SUFFIX):
raise HookError(
f"FAULT_PROJECT must end with {PROJECT_SUFFIX!r}: "
"run make failure_checks",
)
if project == working_project():
raise HookError("FAULT_PROJECT is the working stand, refusing")
return project
def compose_run(
project: str,
*args: str,
stdin: str | None = None,
) -> subprocess.CompletedProcess[str]:
files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))]
return subprocess.run(
["docker", "compose", "-p", project, *files, *args],
cwd=ROOT,
input=stdin,
text=True,
capture_output=True,
check=False,
)
def compose(project: str, *args: str, stdin: str | None = None) -> str:
result = compose_run(project, *args, stdin=stdin)
if result.returncode != 0:
sys.stderr.write(result.stderr)
raise SystemExit(result.returncode)
return result.stdout.strip()
def wait_answers(project: str, name: str) -> str:
"""Ждать, пока сервис ответит своей проверкой из healthcheck.
После `unpause` Docker до следующего запуска healthcheck (до 5 с)
показывает `unhealthy`, и `up --wait` сразу выходит с ошибкой, хотя
сервис уже отвечает. Поэтому проверка — напрямую.
"""
deadline = time.monotonic() + PROBE_TIMEOUT_S
while time.monotonic() < deadline:
probe = compose_run(
project,
"exec",
"-T",
name,
"sh",
"-c",
PROBES[name],
)
if probe.returncode == 0:
return ""
time.sleep(0.2)
raise HookError(f"{name} does not answer in {PROBE_TIMEOUT_S}s")
def valkey(project: str, *args: str) -> str:
# аргументы — позиционные параметры sh, без подстановки в строку
return compose(
project,
"exec",
"-T",
"valkey",
"sh",
"-c",
'exec valkey-cli -p "$VALKEY_PORT" "$@"',
"sh",
*args,
)
def psql(project: str, sql: str, *, title: str = "") -> str:
return compose(
project,
"exec",
"-T",
"postgres",
"sh",
"-c",
'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq '
'-v ON_ERROR_STOP=1 -v title="$1"',
"sh",
title,
stdin=sql,
)
def service(name: str) -> str:
if name not in SERVICES:
raise HookError(f"service must be one of {SERVICES}")
return name
def wait_healthy(project: str, name: str) -> str:
# тот же контейнер, без пересоздания; --wait ждёт его healthcheck
return compose(project, "up", "-d", "--wait", "--no-recreate", name)
def cache_hits(project: str) -> str:
for line in valkey(project, "INFO", "stats").splitlines():
if line.startswith("keyspace_hits:"):
return line.split(":", 1)[1].strip()
raise HookError("keyspace_hits not found in INFO stats")
def cache_has_chat(project: str, chat_id: str) -> str:
database = compose(
project,
"exec",
"-T",
"postgres",
"printenv",
"POSTGRES_DB",
)
key = f"{CACHE_KEY_PREFIX}:{database}:chat:{uuid.UUID(chat_id)}"
return valkey(project, "EXISTS", key)
def run(project: str, action: str, args: list[str]) -> str:
"""Выполнить действие; синтаксис без match: hook запускают и 3.9."""
if action in ("stop", "pause") and len(args) == 1:
return compose(project, action, service(args[0]))
if action == "start" and len(args) == 1:
return wait_healthy(project, service(args[0]))
if action == "unpause" and len(args) == 1:
compose(project, "unpause", service(args[0]))
return wait_answers(project, args[0])
if action == "flush-cache" and not args:
return valkey(project, "FLUSHALL")
if action == "cache-hits" and not args:
return cache_hits(project)
if action == "cache-has-chat" and len(args) == 1:
return cache_has_chat(project, args[0])
if action == "fail-members" and len(args) == 1:
return psql(project, FAIL_MEMBERS_SQL, title=args[0])
if action == "clear-fail-members" and not args:
return psql(project, CLEAR_FAIL_MEMBERS_SQL)
if action == "count-chats" and len(args) == 1:
return psql(project, COUNT_CHATS_SQL, title=args[0])
raise HookError(f"unknown action or arguments: {action} {args}")
def main() -> int:
if len(sys.argv) < 2:
print(__doc__, file=sys.stderr)
return 2
try:
output = run(fault_project(), sys.argv[1], sys.argv[2:])
except (HookError, ValueError) as e:
print(f"fault_hook: {e}", file=sys.stderr)
return 2
if output:
print(output)
return 0
if __name__ == "__main__":
sys.exit(main())
+258
View File
@@ -0,0 +1,258 @@
"""`make failure_checks`: проверки отказов на отдельном стенде.
Поднимает тот же `docker-compose.yml` под проектом `<рабочий>-failures`
с override `student-tests/failures.compose.yml`: свои PostgreSQL и Valkey
со своим volume, порты хранилищ не публикуются. Затем:
- собирает образ из рабочего дерева и применяет миграции;
- запускает два контейнера API: обычный и «тесный» (срок сессии 2 с, пул
из одного соединения);
- прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook
`student-tests/fault_hook.py`;
- удаляет стенд вместе с volume при любом исходе, в том числе по Ctrl+C.
Рабочий стенд, его база и кэш не затрагиваются. Только stdlib. Решения
1, 2, 5 design change `failure-checks`. Запускается `$(PYTHON)`, а не
`uv run`, по той же причине, что `run_isolated.py`.
"""
from __future__ import annotations
import json
import os
import signal
import socket
import subprocess
import sys
import time
import urllib.error
import urllib.request
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
ENV_FILE = ROOT / ".env"
COMPOSE_FILES = (
ROOT / "docker-compose.yml",
ROOT / "student-tests" / "failures.compose.yml",
)
FAULT_HOOK = ROOT / "student-tests" / "fault_hook.py"
PROJECT_SUFFIX = "-failures"
READY_TIMEOUT_S = 60
LOG_TAIL_LINES = 50
# «тесный» API: короткий срок сессии и пул из одного соединения
TIGHT_ENV = {
"AUTH__SESSION_TTL_SECONDS": "2",
"DATABASE__POOL_SIZE": "1",
"DATABASE__MAX_OVERFLOW": "0",
"DATABASE__POOL_TIMEOUT_SECONDS": "1",
"DATABASE__REQUEST_TIMEOUT_SECONDS": "2",
}
def say(message: str) -> None:
print(f"[failure_checks] {message}", flush=True)
def run(
*args: str,
check: bool = True,
quiet: bool = False,
env: dict[str, str] | None = None,
) -> subprocess.CompletedProcess[str]:
"""Команда из корня репозитория; вывод — в терминал, если не quiet."""
return subprocess.run(
args,
cwd=ROOT,
check=check,
text=True,
capture_output=quiet,
env=env,
)
def dc(
project: str,
*args: str,
check: bool = True,
quiet: bool = False,
) -> subprocess.CompletedProcess[str]:
"""docker compose проекта отказов; без `-p` не вызывается никогда."""
files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))]
return run(
"docker",
"compose",
"-p",
project,
*files,
*args,
check=check,
quiet=quiet,
)
def working_project() -> str:
config = run("docker", "compose", "config", "--format", "json", quiet=True)
return json.loads(config.stdout)["name"]
def app_port() -> str:
"""`APP__PORT` из `.env`: на нём слушает API внутри контейнера."""
if ENV_FILE.exists():
for line in ENV_FILE.read_text(encoding="utf-8").splitlines():
if line.strip().startswith("APP__PORT="):
return line.split("=", 1)[1].strip()
return "8080"
def free_port() -> int:
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
return sock.getsockname()[1]
def wait_ready(url: str, container: str) -> None:
deadline = time.monotonic() + READY_TIMEOUT_S
while time.monotonic() < deadline:
try:
with urllib.request.urlopen(url, timeout=2) as response:
if response.status == 200:
return
except (urllib.error.URLError, OSError):
pass
state = run(
"docker",
"inspect",
"-f",
"{{.State.Running}}",
container,
check=False,
quiet=True,
)
if state.stdout.strip() != "true":
raise RuntimeError(f"container {container} is not running")
time.sleep(1)
raise RuntimeError(f"{url} not ready in {READY_TIMEOUT_S}s")
def cleanup(project: str, containers: list[str]) -> bool:
"""Контейнеры API, сервисы и volume проекта отказов; True — чисто."""
for name in containers:
run("docker", "rm", "-f", name, check=False, quiet=True)
down = dc(project, "down", "-v", "--remove-orphans", check=False)
left = run(
"docker",
"volume",
"ls",
"-q",
"--filter",
f"label=com.docker.compose.project={project}",
quiet=True,
check=False,
)
return down.returncode == 0 and not left.stdout.strip()
def start_api(
project: str,
name: str,
port: int,
env: dict[str, str],
) -> str:
env_args = [
arg for key, value in env.items() for arg in ("-e", f"{key}={value}")
]
dc(
project,
"run",
"-d",
"--no-deps",
"--name",
name,
*env_args,
"-p",
f"127.0.0.1:{port}:{app_port()}",
"api",
quiet=True,
)
base_url = f"http://127.0.0.1:{port}"
wait_ready(f"{base_url}/health/ready", name)
return base_url
def main() -> int:
pytest_args = sys.argv[1:]
working = working_project()
project = f"{working}{PROJECT_SUFFIX}"
if project == working or not project.endswith(PROJECT_SUFFIX):
say(f"refusing to use project {project!r}")
return 2
default_name = f"{project}-api"
tight_name = f"{project}-api-tight"
containers = [default_name, tight_name]
say(f"project={project} (working stand: {working})")
if not cleanup(project, containers):
say("leftovers of a previous run could not be removed")
return 1
results: dict[str, int] = {}
failed = True
try:
say("build image")
dc(project, "build", "api")
say("start postgres and valkey")
dc(project, "up", "-d", "--wait", "postgres", "valkey")
say("migrations")
dc(project, "run", "--rm", "migrate")
say("start api containers")
base_url = start_api(project, default_name, free_port(), {})
tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV)
say(f"ready: api={base_url} tight={tight_url}")
env = os.environ | {
"BASE_URL": base_url,
"FAULT_TIGHT_BASE_URL": tight_url,
"FAULT_HOOK": str(FAULT_HOOK),
"FAULT_PROJECT": project,
}
say("pytest -m fault")
results["fault"] = run(
"uv",
"run",
"pytest",
"-m",
"fault",
*pytest_args,
check=False,
env=env,
).returncode
failed = bool(results["fault"])
except KeyboardInterrupt:
say("interrupted")
results["interrupted"] = 130
except (subprocess.CalledProcessError, RuntimeError) as e:
say(f"setup failed: {e}")
results["setup"] = 1
finally:
# повторный Ctrl+C не должен оборвать уборку на полпути
signal.signal(signal.SIGINT, signal.SIG_IGN)
if failed:
for name in containers:
say(f"last {LOG_TAIL_LINES} lines of {name}")
run(
"docker",
"logs",
"--tail",
str(LOG_TAIL_LINES),
name,
check=False,
)
say("cleanup")
if not cleanup(project, containers):
say("cleanup failed")
results["cleanup"] = 1
say(f"results: {results}")
return next((code for code in results.values() if code), 0)
if __name__ == "__main__":
sys.exit(main())
+4 -69
View File
@@ -57,26 +57,6 @@ EXCLUDED: dict[Scenario, Exclusion] = {
reason="срок ключа виден только в Valkey",
check="TTL ключа карточки через valkey-cli — evidence/cache/hits.md",
),
("chat-cache", "Valkey остановлен"): Exclusion(
reason="нужно остановить Valkey, тесты стенд не трогают",
check="evidence/cache/outage.md; автоматическая проверка — "
"change failure-checks",
),
("chat-cache", "Valkey завис"): Exclusion(
reason="нужен docker compose pause для Valkey",
check="evidence/cache/outage.md: время ответа; автоматическая "
"проверка — change failure-checks",
),
("chat-cache", "Valkey вернулся"): Exclusion(
reason="нужно остановить и снова запустить Valkey",
check="evidence/cache/outage.md: warning и info в журнале, "
"ключи снова пишутся; автоматическая проверка — change "
"failure-checks",
),
("chat-cache", "Очистка кэша"): Exclusion(
reason="нужен FLUSHALL в Valkey, тесты стенд не трогают",
check="evidence/cache/flush-restart.md",
),
("chat-cache", "Временная база"): Exclusion(
reason="ключи видны только в Valkey, а набор не знает, на какой "
"базе работает",
@@ -89,38 +69,6 @@ EXCLUDED: dict[Scenario, Exclusion] = {
"прежний токен читает те же данные — "
"evidence/storage/test-persistence.md",
),
("data-storage", "Сбой при добавлении участников"): Exclusion(
reason="нужен сбой БД посреди транзакции: штатным запросом его "
"не вызвать, участники проверяются до вставки",
check="одна транзакция и один commit в ChatService.create_chat; "
"автоматическая проверка отката — change failure-checks",
),
("data-storage", "БД остановлена"): Exclusion(
reason="нужно остановить Postgres, тесты стенд не трогают",
check="evidence/storage/db-unavailable.md; автоматическая "
"проверка — change failure-checks",
),
("data-storage", "БД вернулась"): Exclusion(
reason="нужно остановить и снова запустить Postgres",
check="evidence/storage/db-unavailable.md; автоматическая "
"проверка — change failure-checks",
),
("data-storage", "Соединения исчерпаны"): Exclusion(
reason="нужны пул из одного соединения и замороженный Postgres",
check="evidence/storage/pool-timeout.md; автоматическая "
"проверка — change failure-checks",
),
("health", "Хранилище не готово"): Exclusion(
reason="нужно остановить Postgres, тесты стенд не трогают",
check="evidence/storage/db-unavailable.md: /health/ready — 503, "
"/health/live — 200; автоматическая проверка — change "
"failure-checks",
),
("health", "Кэш недоступен"): Exclusion(
reason="нужно остановить Valkey, тесты стенд не трогают",
check="evidence/cache/outage.md: /health/ready — 200; "
"автоматическая проверка — change failure-checks",
),
("identification", "Кнопка Authorize в Swagger"): Exclusion(
reason="это интерфейс /docs в браузере",
check="схемы bearerAuth и basicAuth, из которых строится кнопка, "
@@ -132,27 +80,11 @@ EXCLUDED: dict[Scenario, Exclusion] = {
check="поиск выданного токена по всем таблицам через psql — "
"evidence/auth/passwords-and-tokens.md",
),
("sessions", "Истёкший токен"): Exclusion(
reason="нужен сервис со сроком сессии 2 с, а обычный стенд — с 3600 с",
check="AUTH__SESSION_TTL_SECONDS=2 — evidence/auth/expiry.md; "
"автоматическая проверка — change failure-checks",
),
("sessions", "Срок не продлевается"): Exclusion(
reason="нужен сервис со сроком сессии 2 с",
check="запросы каждые 0,5 с при сроке 2 с — "
"evidence/auth/expiry.md; автоматическая проверка — change "
"failure-checks",
),
("sessions", "Прежний токен после рестарта"): Exclusion(
reason="нужен рестарт стенда, тесты сервер не трогают",
check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — "
"evidence/storage/test-persistence.md",
),
("sessions", "БД остановлена при запросе с токеном"): Exclusion(
reason="нужно остановить Postgres, тесты стенд не трогают",
check="evidence/auth/expiry.md; автоматическая проверка — "
"change failure-checks",
),
("users", "Хэш в БД"): Exclusion(
reason="нужен доступ к таблице users, а тесты ходят по HTTP",
check="строки users через psql: префикс $argon2id$ и разные "
@@ -163,10 +95,13 @@ EXCLUDED: dict[Scenario, Exclusion] = {
@dataclass
class Collected:
"""Что собрал pytest: маркеры `spec` и модули тестов."""
"""Что собрал 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]()
+4 -2
View File
@@ -34,10 +34,12 @@ def test_every_scenario_is_covered(request: pytest.FixtureRequest) -> None:
scenarios = all_scenarios()
problems = coverage_problems(scenarios, collected.marks, EXCLUDED)
tested = len(scenarios & collected.marks.keys())
# тесты fault выполняет только make failure_checks
by_fault = len(scenarios & collected.fault)
print(
f"coverage: {len(scenarios)} scenarios in "
f"{len(CAPABILITIES)} specs, {tested} tested, "
f"{len(EXCLUDED)} excluded",
f"{len(CAPABILITIES)} specs, {tested} tested "
f"({by_fault} by make failure_checks), {len(EXCLUDED)} excluded",
)
assert not problems, "\n".join(problems)
+327
View File
@@ -0,0 +1,327 @@
"""Проверки отказов: выполняет только `make failure_checks` (маркер `fault`).
Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres и
Valkey, обычный API (`BASE_URL`) и «тесный» (срок сессии 2 с, пул из
одного соединения). На хранилища тесты действуют только через фикстуру
`stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в
рабочее состояние. Решение 4 design change `failure-checks`.
"""
import statistics
import threading
import time
import uuid
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from typing import Any
import httpx
import pytest
from api_client import API, Actor, Api
from contract import (
BEARER_CHALLENGE,
assert_error,
assert_ok,
assert_unauthorized,
)
pytestmark = pytest.mark.fault
type Stand = Callable[..., str]
RESTORE = {"stop": "start", "pause": "unpause"}
# запас к границам времени: планировщик Docker Desktop
SLACK_S = 0.3
# [cache] timeout_seconds и retry_after_seconds по умолчанию
CACHE_TIMEOUT_S = 0.2
CACHE_RETRY_AFTER_S = 5
# окружение «тесного» API (TIGHT_ENV в run_failures.py)
SESSION_TTL_S = 2
POOL_TIMEOUT_S = 1
# срок проверки Postgres в /health/ready
READINESS_TIMEOUT_S = 2
ME = f"{API}/users/me"
@contextmanager
def outage(stand: Stand, action: str, service: str) -> Iterator[None]:
"""`stop` или `pause` хранилища; в `finally` — обратно."""
stand(action, service)
try:
yield
finally:
stand(RESTORE[action], service)
def timed(
call: Callable[[], httpx.Response],
) -> tuple[httpx.Response, float]:
started = time.monotonic()
resp = call()
return resp, time.monotonic() - started
def read_chat(api: Api, actor: Actor, chat: dict[str, Any]) -> httpx.Response:
return api.request("GET", f"{API}/chats/{chat['id']}", actor=actor)
def wait_cache_ready(
api: Api,
stand: Stand,
actor: Actor,
chat: dict[str, Any],
) -> None:
"""Дождаться, пока чтение снова пишет карточку в кэш.
После отказа в прошлом тесте API пропускает кэш ещё до 5 с.
"""
deadline = time.monotonic() + CACHE_RETRY_AFTER_S + 2
stand("flush-cache")
while time.monotonic() < deadline:
assert_ok(read_chat(api, actor, chat), 200, "Chat")
if stand("cache-has-chat", chat["id"]) == "1":
return
time.sleep(0.5)
raise AssertionError("cache did not come back")
def chat_titles(api: Api, actor: Actor) -> set[str]:
return {
chat["title"]
for page in api.chat_pages(actor)
for chat in page["items"]
}
# ---------------------------------------------------------------------------
# Сессии: срок 2 с на «тесном» API, БД остановлена — на обычном
# ---------------------------------------------------------------------------
@pytest.mark.spec("sessions", "Истёкший токен")
def test_expired_token(tight_api: Api) -> None:
actor = tight_api.register()
assert_ok(tight_api.request("GET", ME, actor=actor), 200, "User")
time.sleep(SESSION_TTL_S + 1)
assert_unauthorized(
tight_api.request("GET", ME, actor=actor),
BEARER_CHALLENGE,
)
@pytest.mark.spec("sessions", "Срок не продлевается")
def test_use_does_not_extend_session(tight_api: Api) -> None:
actor = tight_api.register()
logged_in = time.monotonic()
successes = 0
while time.monotonic() - logged_in < SESSION_TTL_S - SLACK_S:
assert_ok(tight_api.request("GET", ME, actor=actor), 200, "User")
successes += 1
time.sleep(0.5)
assert successes >= 3, "too few requests before expiry"
time.sleep(max(0.0, logged_in + SESSION_TTL_S + 1 - time.monotonic()))
assert_unauthorized(
tight_api.request("GET", ME, actor=actor),
BEARER_CHALLENGE,
)
@pytest.mark.spec("sessions", "БД остановлена при запросе с токеном")
def test_token_while_database_stopped(api: Api, stand: Stand) -> None:
actor = api.register()
with outage(stand, "stop", "postgres"):
resp = api.request("GET", ME, actor=actor)
assert_error(resp, 503)
# недоступность хранилища — не отказ в аутентификации
assert "WWW-Authenticate" not in resp.headers
assert_ok(api.request("GET", ME, actor=actor), 200, "User")
# ---------------------------------------------------------------------------
# Хранение: откат, остановленная БД, исчерпанный пул
# ---------------------------------------------------------------------------
@pytest.mark.spec("data-storage", "Сбой при добавлении участников")
def test_members_failure_rolls_back_chat(
api: Api,
stand: Stand,
alice: Actor,
bob: Actor,
) -> None:
title = f"fault-{uuid.uuid4().hex}"
stand("fail-members", title)
try:
resp = api.request(
"POST",
f"{API}/chats",
actor=alice,
json={"title": title, "member_ids": [alice.id, bob.id]},
)
assert_error(resp, 500)
finally:
stand("clear-fail-members")
for actor in (alice, bob):
assert title not in chat_titles(api, actor)
assert stand("count-chats", title) == "0"
@pytest.mark.spec("data-storage", "БД остановлена")
@pytest.mark.spec("data-storage", "БД вернулась")
def test_database_stopped_and_back(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
path = f"{API}/chats/{chat['id']}/messages"
with outage(stand, "stop", "postgres"):
resp, took = timed(
lambda: api.request(
"POST",
path,
actor=alice,
json={"text": "во время отказа"},
),
)
error = assert_error(resp, 503)
assert took < 2, f"503 took {took:.2f}s"
for word in ("postgres", "sql", "connect"):
assert word not in error["message"].lower()
message = api.send_message(alice, chat["id"], "после возврата")
# запись во время отказа не зафиксирована, новая — видна
assert api.all_messages(alice, chat["id"]) == [message]
@pytest.mark.spec("data-storage", "Соединения исчерпаны")
def test_pool_exhausted(tight_api: Api, stand: Stand) -> None:
actor = tight_api.register()
holder = Api(str(tight_api.client.base_url), timeout=15)
first: list[int] = []
def hold_connection() -> None:
first.append(holder.request("GET", ME, actor=actor).status_code)
with outage(stand, "pause", "postgres"):
thread = threading.Thread(target=hold_connection)
thread.start()
time.sleep(SLACK_S)
resp, took = timed(lambda: tight_api.request("GET", ME, actor=actor))
assert_error(resp, 503)
assert took < POOL_TIMEOUT_S + 0.5, f"503 took {took:.2f}s"
thread.join()
holder.close()
assert first == [503]
# срок сессии 2 с мог истечь за время паузы: проверяем пул новым входом
fresh = tight_api.register()
assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User")
# ---------------------------------------------------------------------------
# Readiness
# ---------------------------------------------------------------------------
@pytest.mark.spec("health", "Хранилище не готово")
def test_readiness_without_database(api: Api, stand: Stand) -> None:
with outage(stand, "stop", "postgres"):
resp, took = timed(lambda: api.request("GET", "/health/ready"))
assert_error(resp, 503)
assert took < READINESS_TIMEOUT_S + 0.5, f"ready took {took:.2f}s"
live = api.request("GET", "/health/live")
assert live.status_code == 200
assert api.request("GET", "/health/ready").status_code == 200
@pytest.mark.spec("health", "Кэш недоступен")
def test_readiness_without_cache(api: Api, stand: Stand) -> None:
with outage(stand, "stop", "valkey"):
assert api.request("GET", "/health/ready").status_code == 200
# ---------------------------------------------------------------------------
# Кэш карточки чата
# ---------------------------------------------------------------------------
@pytest.mark.spec("chat-cache", "Очистка кэша")
def test_flush_cache(
api: Api,
stand: Stand,
bob: Actor,
chat: dict[str, Any],
) -> None:
wait_cache_ready(api, stand, bob, chat)
stand("flush-cache")
assert stand("cache-has-chat", chat["id"]) == "0"
assert assert_ok(read_chat(api, bob, chat), 200, "Chat") == chat
assert stand("cache-has-chat", chat["id"]) == "1"
@pytest.mark.spec("chat-cache", "Valkey остановлен")
def test_valkey_stopped(
api: Api,
stand: Stand,
alice: Actor,
bob: Actor,
chat: dict[str, Any],
) -> None:
path = f"{API}/chats/{chat['id']}/messages"
sent = [api.send_message(alice, chat["id"], "до отказа")]
with outage(stand, "stop", "valkey"):
resp, took = timed(lambda: read_chat(api, bob, chat))
assert assert_ok(resp, 200, "Chat") == chat
assert took < CACHE_TIMEOUT_S + SLACK_S, f"read took {took:.2f}s"
resp, took = timed(
lambda: api.request(
"POST",
path,
actor=alice,
json={"text": "во время отказа"},
),
)
sent.append(assert_ok(resp, 201, "Message"))
assert took < CACHE_TIMEOUT_S + SLACK_S, f"send took {took:.2f}s"
assert api.all_messages(bob, chat["id"]) == sent
@pytest.mark.spec("chat-cache", "Valkey завис")
def test_valkey_paused(
api: Api,
stand: Stand,
bob: Actor,
chat: dict[str, Any],
) -> None:
wait_cache_ready(api, stand, bob, chat)
baseline = statistics.median(
timed(lambda: read_chat(api, bob, chat))[1] for _ in range(5)
)
with outage(stand, "pause", "valkey"):
resp, took = timed(lambda: read_chat(api, bob, chat))
assert assert_ok(resp, 200, "Chat") == chat
assert took < baseline + CACHE_TIMEOUT_S + SLACK_S, (
f"read took {took:.2f}s, baseline {baseline:.3f}s"
)
# окно пропуска: следующий запрос таймаута не ждёт
resp, took = timed(lambda: read_chat(api, bob, chat))
assert assert_ok(resp, 200, "Chat") == chat
assert took < CACHE_TIMEOUT_S, f"second read took {took:.2f}s"
@pytest.mark.spec("chat-cache", "Valkey вернулся")
def test_valkey_back(
api: Api,
stand: Stand,
bob: Actor,
chat: dict[str, Any],
) -> None:
with outage(stand, "stop", "valkey"):
assert_ok(read_chat(api, bob, chat), 200, "Chat")
# API не перезапускался; кэш снова в работе после окна пропуска
time.sleep(CACHE_RETRY_AFTER_S + 0.5)
assert_ok(read_chat(api, bob, chat), 200, "Chat")
assert stand("cache-has-chat", chat["id"]) == "1"
hits = int(stand("cache-hits"))
assert assert_ok(read_chat(api, bob, chat), 200, "Chat") == chat
assert int(stand("cache-hits")) > hits