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 общий с рабочим стендом, ключи кэша базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша
разделены именем базы. Скрипт запускается `$(PYTHON)`, а не разделены именем базы. Скрипт запускается `$(PYTHON)`, а не
`uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. `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 ## Troubleshooting
+36 -9
View File
@@ -46,13 +46,39 @@ paths:
Его вывод — evidence набора против контейнера. Его вывод — evidence набора против контейнера.
`make student_test` — против любого запущенного стенда (`BASE_URL`), `make student_test` — против любого запущенного стенда (`BASE_URL`),
он оставляет данные в рабочей базе. он оставляет данные в рабочей базе.
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные - Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или
Postgres или Valkey), обычный прогон не подходит. Попадание в кэш по замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный
HTTP не отличить от чтения из БД: такие сценарии `chat-cache` — прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль
исключения с evidence. Сами тесты `test_failures.py`, команда `make failure_checks` (change
контейнеры не трогают: стенд готовит явный hook или отдельная цель `failure-checks`). Попадание в кэш по HTTP не отличить от чтения из
Makefile, как `make test-persistence` в skeleton. Механизм выбирает БД: такие сценарии `chat-cache` — исключения с evidence.
change `failure-checks`. - Как устроен `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`). `evidence/` (`evidence/README.md`).
- `tests/` — публичные проверки skeleton: не править, не ослаблять, - `tests/` — публичные проверки skeleton: не править, не ослаблять,
@@ -76,8 +102,9 @@ paths:
- **Каждый тест сценария спека помечен** `@pytest.mark.spec("<capability>", - **Каждый тест сценария спека помечен** `@pytest.mark.spec("<capability>",
"<Сценарий>")`, имя — дословно из `#### Scenario:`. Новый сценарий в "<Сценарий>")`, имя — дословно из `#### Scenario:`. Новый сценарий в
основном спеке без теста роняет `test_coverage.py`. Если его нельзя основном спеке без теста роняет `test_coverage.py`. Если его нельзя
проверить по HTTP, добавить запись в `EXCLUDED` (`spec_coverage.py`) проверить по HTTP даже на стенде отказов, добавить запись в
с причиной и способом проверки. `EXCLUDED` (`spec_coverage.py`) с причиной и способом проверки.
Сценарии тестов `fault` сверка считает покрытыми и печатает их число.
- Модуль сверки называется `spec_coverage.py`, а не `coverage.py`: - Модуль сверки называется `spec_coverage.py`, а не `coverage.py`:
каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы
пакет `coverage` (pytest-cov, coverage-runner IDE). пакет `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 ```bash
make check # офлайн-структура skeleton make check # офлайн-структура skeleton
make test_isolated # образ на временной базе: smoke + student-tests, уборка 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 python3 $D all # живой сервер + flow + smoke + student-tests
make lint # ruff; затрагивает и driver.py make lint # ruff; затрагивает и driver.py
``` ```
Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у
`flow`, smoke — `PASS: lab2 public API scenario...`, student — все `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 ## Gotchas
+10 -13
View File
@@ -81,22 +81,14 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).
Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на
PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change
`session-auth`, кэш Valkey — change `membership-cache`. Этот файл и `session-auth`, кэш Valkey — change `membership-cache`, автоматические
проверки отказов — change `failure-checks`. Этот файл и
`.claude/rules/` описывают целевое состояние лабы 2, поэтому в `.claude/rules/` описывают целевое состояние лабы 2, поэтому в
остальном код с ними пока расходится: остальном код с ними пока расходится:
- `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с - `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с
`X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` — `X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` —
change `bench-postgres` (`bench.md`); 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 после восстановления - в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления
базы: иначе в кэше останутся карточки чатов, созданных после снятия базы: иначе в кэше останутся карточки чатов, созданных после снятия
backup (design change `membership-cache`, Risks); 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 revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` | | `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 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 [BENCH_LABEL=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) |
| `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | | `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт |
| `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность | | `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность |
@@ -310,13 +303,17 @@ src/
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
cursor.py # непрозрачный keyset-курсор: кодирование и разбор cursor.py # непрозрачный keyset-курсор: кодирование и разбор
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test 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() — единственное место идентификации api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4 test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib) 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 bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick
run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json
k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы
@@ -335,7 +332,7 @@ evidence/storage/ # отказы БД, пул, statement_timeout, р
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт 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/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
evidence/profile/<метка>.txt # результаты make bench_inproc evidence/profile/<метка>.txt # результаты make bench_inproc
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
+9
View File
@@ -191,6 +191,15 @@ student_test:
test_isolated: env_setup start_db start_cache test_isolated: env_setup start_db start_cache
$(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) $(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 .PHONY: lint
lint: lint:
@ruff format . @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: Запуск одной командой ### Requirement: Запуск одной командой
Весь набор SHALL запускаться одной командой `make student_test` против Набор, кроме проверок отказов (требование «Проверки отказов на
сервера по адресу `BASE_URL`, по умолчанию `http://localhost:8080`. отдельном стенде»), SHALL запускаться одной командой `make student_test`
Команда SHALL завершаться с кодом 0, только если прошли все тесты. Если против сервера по адресу `BASE_URL`, по умолчанию
сервер по `BASE_URL` не отвечает, набор MUST завершаться с ненулевым `http://localhost:8080`. Команда SHALL завершаться с кодом 0, только
кодом и сообщением о недоступности адреса, а не множеством ошибок если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор
отдельных тестов. MUST завершаться с ненулевым кодом и сообщением о недоступности адреса,
а не множеством ошибок отдельных тестов.
#### Scenario: Все тесты прошли #### Scenario: Все тесты прошли
- **WHEN** сервер запущен и `make student_test` выполняется без - **WHEN** сервер запущен и `make student_test` выполняется без
аргументов аргументов
- **THEN** все тесты проходят, команда завершается с кодом 0 - **THEN** все тесты, кроме проверок отказов, проходят, команда
завершается с кодом 0, а проверки отказов в прогоне не выполняются
#### Scenario: Другой адрес #### Scenario: Другой адрес
@@ -38,9 +40,12 @@
### Requirement: Только по HTTP ### Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Один и тот же набор код приложения, запускать или останавливать сервер. Проверки отказов
SHALL проходить против сервера, запущенного на хосте, и против SHALL действовать на хранилища стенда и узнавать их состояние только
контейнера. через hook, который им передаёт `make failure_checks`. Без hook они
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
запущенного на хосте, и против контейнера.
#### Scenario: Консоль и контейнер #### Scenario: Консоль и контейнер
@@ -48,6 +53,13 @@ SHALL проходить против сервера, запущенного н
`make run_docker` `make run_docker`
- **THEN** оба прогона проходят одинаково - **THEN** оба прогона проходят одинаково
#### Scenario: Проверка отказа без hook
- **WHEN** проверки отказов запущены pytest напрямую, без
`make failure_checks`
- **THEN** они завершаются ошибкой, которая называет `make
failure_checks`, и ни одно хранилище не останавливается
### Requirement: Независимость прогонов ### Requirement: Независимость прогонов
Каждый тест SHALL создавать собственных пользователей с уникальным Каждый тест SHALL создавать собственных пользователей с уникальным
@@ -136,10 +148,13 @@ SHALL проходить против сервера, запущенного н
Для каждого сценария основных спеков `api-conventions`, Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`, `identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache` и `health`, который `pagination`, `data-storage`, `chat-cache` и `health`, который
воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из воспроизводится по HTTP против работающего сервера, в том числе на
имени или описания теста SHALL быть понятно, какой capability и стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть
сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести, понятно, какой capability и сценарий он проверяет. Сценарий, который
SHALL быть перечислены с причиной и способом проверки. проверяет тест отказа, SHALL считаться покрытым, хотя `make
student_test` этот тест не выполняет; итог сверки SHALL называть, сколько
сценариев покрыто проверками отказов. Сценарии, которые по HTTP не
воспроизвести, SHALL быть перечислены с причиной и способом проверки.
#### Scenario: Сверка покрытия #### Scenario: Сверка покрытия
@@ -147,6 +162,12 @@ SHALL быть перечислены с причиной и способом п
- **THEN** находится проверяющий его тест либо запись в списке - **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Проверка формы ответов ### Requirement: Проверка формы ответов
Тесты SHALL проверять не только статус. Тесты SHALL проверять не только статус.
@@ -163,10 +184,11 @@ SHALL быть перечислены с причиной и способом п
### Requirement: Результат прогона сохраняется ### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера SHALL сохраняться в `evidence/` с Вывод прогона против контейнера (`make test_isolated`) и вывод `make
командой, датой, commit, адресом стенда и итогом. `REPORT.md` SHALL failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
ссылаться на него в строках уровня «4»: собственные тесты и 100 commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
сообщений от 10 клиентов. строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и
автоматические проверки истечения сессии и недоступности БД и Valkey.
#### Scenario: Доказательство в отчёте #### Scenario: Доказательство в отчёте
@@ -222,3 +244,53 @@ MUST NOT затрагиваться, а карточки чатов тестов
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>` - **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"] testpaths = ["student-tests"]
# каталог с дефисом не пакет: хелперы импортируются как модули # каталог с дефисом не пакет: хелперы импортируются как модули
pythonpath = ["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 = [ markers = [
"spec(capability, scenario): сценарий основного спека, который проверяет тест", "spec(capability, scenario): сценарий основного спека, который проверяет тест",
"fault: проверка отказа хранилища; нужен стенд make failure_checks и его hook",
] ]
[tool.hatch.build.targets.wheel] [tool.hatch.build.targets.wheel]
+60 -1
View File
@@ -1,7 +1,8 @@
"""Настройка набора: адрес стенда, проверка доступности, фикстуры.""" """Настройка набора: адрес стенда, проверка доступности, фикстуры."""
import os import os
from collections.abc import Iterator import subprocess
from collections.abc import Callable, Iterator
from typing import Any from typing import Any
import httpx import httpx
@@ -11,6 +12,10 @@ from api_client import Actor, Api
from spec_coverage import COLLECTED, Collected from spec_coverage import COLLECTED, Collected
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") 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) @pytest.hookimpl(tryfirst=True)
@@ -22,15 +27,35 @@ def pytest_collection_modifyitems(
collected = Collected() collected = Collected()
for item in items: for item in items:
collected.modules.add(item.path.name) collected.modules.add(item.path.name)
is_fault = item.get_closest_marker("fault") is not None
for mark in item.iter_markers("spec"): for mark in item.iter_markers("spec"):
if len(mark.args) != 2 or mark.kwargs: if len(mark.args) != 2 or mark.kwargs:
raise pytest.UsageError( raise pytest.UsageError(
f"{item.nodeid}: spec marker takes (capability, scenario)", f"{item.nodeid}: spec marker takes (capability, scenario)",
) )
collected.marks.setdefault(mark.args, []).append(item.nodeid) collected.marks.setdefault(mark.args, []).append(item.nodeid)
if is_fault:
collected.fault.add(mark.args)
config.stash[COLLECTED] = collected 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) @pytest.fixture(scope="session", autouse=True)
def _server_reachable() -> None: def _server_reachable() -> None:
"""Без сервера прогон останавливается одной строкой, а не 100 ошибками.""" """Без сервера прогон останавливается одной строкой, а не 100 ошибками."""
@@ -80,3 +105,37 @@ def eve(api: Api) -> Actor:
def chat(api: Api, alice: Actor, bob: Actor) -> dict[str, Any]: def chat(api: Api, alice: Actor, bob: Actor) -> dict[str, Any]:
"""Чат Алисы и Боба.""" """Чат Алисы и Боба."""
return api.create_chat(alice, bob, title="Алиса и Боб") 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", reason="срок ключа виден только в Valkey",
check="TTL ключа карточки через valkey-cli — evidence/cache/hits.md", 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( ("chat-cache", "Временная база"): Exclusion(
reason="ключи видны только в Valkey, а набор не знает, на какой " reason="ключи видны только в Valkey, а набор не знает, на какой "
"базе работает", "базе работает",
@@ -89,38 +69,6 @@ EXCLUDED: dict[Scenario, Exclusion] = {
"прежний токен читает те же данные — " "прежний токен читает те же данные — "
"evidence/storage/test-persistence.md", "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( ("identification", "Кнопка Authorize в Swagger"): Exclusion(
reason="это интерфейс /docs в браузере", reason="это интерфейс /docs в браузере",
check="схемы bearerAuth и basicAuth, из которых строится кнопка, " check="схемы bearerAuth и basicAuth, из которых строится кнопка, "
@@ -132,27 +80,11 @@ EXCLUDED: dict[Scenario, Exclusion] = {
check="поиск выданного токена по всем таблицам через psql — " check="поиск выданного токена по всем таблицам через psql — "
"evidence/auth/passwords-and-tokens.md", "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( ("sessions", "Прежний токен после рестарта"): Exclusion(
reason="нужен рестарт стенда, тесты сервер не трогают", reason="нужен рестарт стенда, тесты сервер не трогают",
check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — " check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — "
"evidence/storage/test-persistence.md", "evidence/storage/test-persistence.md",
), ),
("sessions", "БД остановлена при запросе с токеном"): Exclusion(
reason="нужно остановить Postgres, тесты стенд не трогают",
check="evidence/auth/expiry.md; автоматическая проверка — "
"change failure-checks",
),
("users", "Хэш в БД"): Exclusion( ("users", "Хэш в БД"): Exclusion(
reason="нужен доступ к таблице users, а тесты ходят по HTTP", reason="нужен доступ к таблице users, а тесты ходят по HTTP",
check="строки users через psql: префикс $argon2id$ и разные " check="строки users через psql: префикс $argon2id$ и разные "
@@ -163,10 +95,13 @@ EXCLUDED: dict[Scenario, Exclusion] = {
@dataclass @dataclass
class Collected: class Collected:
"""Что собрал pytest: маркеры `spec` и модули тестов.""" """Что собрал pytest: маркеры `spec`, модули тестов и сценарии,
которые проверяют тесты `fault` (их выполняет только
`make failure_checks`)."""
marks: dict[Scenario, list[str]] = field(default_factory=dict) marks: dict[Scenario, list[str]] = field(default_factory=dict)
modules: set[str] = field(default_factory=set) modules: set[str] = field(default_factory=set)
fault: set[Scenario] = field(default_factory=set)
COLLECTED = pytest.StashKey[Collected]() 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() scenarios = all_scenarios()
problems = coverage_problems(scenarios, collected.marks, EXCLUDED) problems = coverage_problems(scenarios, collected.marks, EXCLUDED)
tested = len(scenarios & collected.marks.keys()) tested = len(scenarios & collected.marks.keys())
# тесты fault выполняет только make failure_checks
by_fault = len(scenarios & collected.fault)
print( print(
f"coverage: {len(scenarios)} scenarios in " f"coverage: {len(scenarios)} scenarios in "
f"{len(CAPABILITIES)} specs, {tested} tested, " f"{len(CAPABILITIES)} specs, {tested} tested "
f"{len(EXCLUDED)} excluded", f"({by_fault} by make failure_checks), {len(EXCLUDED)} excluded",
) )
assert not problems, "\n".join(problems) 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