Files
mtusi2026lab3/openspec/changes/replicas-lb/specs/student-tests/spec.md
T
ricoromaandClaude Opus 5.5 8e15e02898 docs: propose replicas-lb change
HAProxy as the single entry point, API replicas without published
ports, resource limits and per-service secrets, restart and stop-one
hooks, replica tests in student-tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:40:04 +03:00

115 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spec Delta
## ADDED Requirements
### Requirement: Тесты реплик через балансировщик
Набор SHALL содержать тесты, которым нужны две и больше реплики за
`BASE_URL`:
- распределение одной сессии по репликам и чтение записи через другую
реплику (capability `load-balancing`);
- повтор с тем же ключом через другую реплику и гонка одного ключа с
ответами разных реплик, пересекающимися по времени (capability
`idempotency`).
Сколько реплик ожидается за `BASE_URL`, набор SHALL узнавать из
переменной `EXPECT_REPLICAS`, а не угадывать по ответам. `make
student_test` SHALL брать её из `API_REPLICAS` (по умолчанию 2), `make
test_isolated` и прогон драйвера против своего процесса в консоли SHALL
передавать 1. При `EXPECT_REPLICAS` = 1 тесты реплик SHALL
пропускаться с причиной, которая называет режим одного процесса. Они
MUST NOT считаться пройденными. При `EXPECT_REPLICAS` ≥ 2 тест SHALL
падать, если ответы дали меньше двух разных `X-Instance-Id`, и
сообщение SHALL называть число увиденных значений.
#### Scenario: Против стенда с балансировщиком
- **WHEN** стенд запущен `make run_docker`, и выполнен `make
student_test`
- **THEN** тесты реплик выполняются и проходят, а их вывод показывает
увиденные `X-Instance-Id`
#### Scenario: Против одного процесса
- **WHEN** выполнен `make test_isolated` или `make student_test
EXPECT_REPLICAS=1` против одного процесса API
- **THEN** тесты реплик помечены пропущенными с причиной «один
процесс», остальные тесты проходят, и код выхода 0
#### Scenario: Реплик меньше ожидаемого
- **WHEN** `make student_test` с `EXPECT_REPLICAS=2` запущен против
одного процесса API
- **THEN** тесты реплик падают с сообщением, что увидено одно значение
`X-Instance-Id`, а не пропускаются
## MODIFIED Requirements
### Requirement: Прогон на временной базе
`make test_isolated` SHALL проверять образ, собранный из рабочего
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
PostgreSQL стенда, с Valkey стенда. Команда SHALL: поднять PostgreSQL и
Valkey, собрать образ, создать базу заново, применить к ней миграции
сервисом миграций compose, запустить отдельный контейнер API из
определения сервиса compose, в котором подменено только имя базы,
опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться
готовности, выполнить публичный smoke (`make test`) и весь набор
(`make student_test`) против этого контейнера, затем остановить и
удалить контейнер и удалить базу. Это один процесс API без
балансировщика: набор SHALL запускаться с `EXPECT_REPLICAS=1`, и тесты
реплик пропускаются с причиной. Код выхода SHALL быть ненулевым, если
не прошёл smoke, набор или уборка. Рабочая база и рабочие контейнеры
стенда MUST NOT затрагиваться, а карточки чатов тестового прогона в
Valkey отделены от рабочих именем базы в ключе (capability
`chat-cache`). Параллельный запуск двух прогонов не поддерживается.
#### Scenario: Успешный прогон
- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и
выполнен `make test_isolated`
- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной,
код выхода 0, ни базы `test_<db>`, ни тестового контейнера после
команды нет, число строк в таблицах рабочей базы не изменилось, а
рабочий стенд продолжает отвечать через балансировщик
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база `test_<db>` удалена
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>`
удалена
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовый контейнер или база `test_<db>` остались от прогона,
убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера (`make test_isolated`), вывод `make
student_test` против стенда с балансировщиком и вывод `make
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов,
гонка одного ключа через реплики и автоматические проверки истечения
сессии и недоступности БД и Valkey.
#### Scenario: Доказательство в отчёте
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
вывода в `evidence/`