Files
mtusi2026lab3/openspec/specs/student-tests/spec.md
T
ricoromaandClaude Opus 5.5 ab71c3b51e feat: put API replicas behind HAProxy
HAProxy 3.4 is the only published entry point; api runs as
API_REPLICAS replicas without ports, found through Docker DNS and
checked on /health/ready. Retries only on connection failure, LB errors
in the contract error format, resource limits and per-service secrets.
Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas /
instances / lb_stats and replica tests driven by EXPECT_REPLICAS.

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

358 lines
22 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.
# student-tests Specification
## Purpose
Собственный набор black-box тестов API мессенджера: одной командой
проверяет по HTTP любой запущенный стенд. Покрывает обязательные
сценарии рубрики, гонки и сценарии основных спеков, а результат прогона
сохраняется как доказательство.
## 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: Независимость прогонов
Каждый тест SHALL создавать собственных пользователей с уникальным
`username` и собственные чаты. Результат MUST NOT зависеть от порядка
тестов, от данных, уже лежащих на сервере, и от предыдущих прогонов.
#### Scenario: Два прогона подряд
- **WHEN** набор запускается дважды подряд против одного сервера без
рестарта
- **THEN** оба прогона проходят
### Requirement: Обязательные сценарии рубрики
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
нескольких страниц истории, а с лабы 2 — неверный пароль и logout.
#### Scenario: Неверный JSON
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
- **THEN** проверяется ответ 400 с `code` `invalid_request`
#### Scenario: Чужой чат
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
историю и пишет в чат
- **THEN** проверяется, что все три запроса получают 404 `not_found`
#### Scenario: Пустое сообщение
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
появляется в истории
#### Scenario: Дубликат username
- **WHEN** регистрируется `username`, который уже занят
- **THEN** проверяется ответ 409 `conflict`
#### Scenario: Обход нескольких страниц
- **WHEN** история содержит больше сообщений, чем помещается на одну
страницу, и тест обходит её по `next_cursor`, в том числе меняя
`limit` между страницами
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
в порядке `(created_at, id)`, а последняя страница имеет
`next_cursor` null
#### Scenario: Неверный пароль в рубрике
- **WHEN** зарегистрированный пользователь входит с неверным паролем
- **THEN** проверяется ответ 401 с `WWW-Authenticate` схемы `Basic`, и
выданного токена в ответе нет
#### Scenario: Logout в рубрике
- **WHEN** пользователь выходит, а затем повторяет запрос прежним
токеном
- **THEN** проверяется ответ 204 на выход и 401 с `WWW-Authenticate`
схемы `Bearer` на повтор
### Requirement: Тест гонок
Набор SHALL содержать тест гонок с реальной параллельностью: запросы
находятся в обработке одновременно, по отдельным соединениям. 10
клиентов SHALL одновременно отправлять по 10 сообщений в один чат, после
чего полный обход истории SHALL давать ровно 100 сообщений с
уникальными `id`. Отдельный тест SHALL одновременно регистрировать
одинаковый `username` несколькими клиентами. Ещё один тест SHALL
одновременно отправлять одно тело с одним `Idempotency-Key` несколькими
клиентами.
#### Scenario: 100 сообщений от 10 клиентов
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений
- **THEN** получено 100 ответов 201, полный обход истории возвращает
100 сообщений с уникальными `id`, и каждое отправленное сообщение
найдено ровно один раз
#### Scenario: Гонка за username
- **WHEN** 10 клиентов одновременно регистрируют одинаковый `username`
- **THEN** ровно один ответ 201, остальные 409 `conflict`
#### Scenario: Гонка одного ключа
- **WHEN** 10 клиентов одновременно отправляют одно тело с одним
`Idempotency-Key`, и не меньше двух запросов были в обработке
одновременно
- **THEN** все ответы 201 с одним `id`, а в истории ровно одно такое
сообщение
### 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`, а не пропускаются
### Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache`, `health` и `idempotency`,
который воспроизводится по HTTP против работающего сервера, в том числе
на стенде отказов, SHALL быть тест. Из имени или описания теста SHALL
быть понятно, какой capability и сценарий он проверяет. Сценарий,
который проверяет тест отказа, SHALL считаться покрытым, хотя `make
student_test` этот тест не выполняет; итог сверки SHALL называть,
сколько сценариев покрыто проверками отказов. Сценарии, которые по HTTP
не воспроизвести, SHALL быть перечислены с причиной и способом
проверки.
#### Scenario: Сверка покрытия
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Проверка формы ответов
Тесты SHALL проверять не только статус.
- У ошибок: тело — ровно `{"error": {"code", "message",
"request_id"}}`, `code` соответствует статусу, `request_id` равен
заголовку `X-Request-Id`.
- У успешных ответов: поля совпадают со схемой контракта, лишних нет,
`id` — UUID в нижнем регистре, `created_at` — RFC 3339 UTC с `Z`.
#### Scenario: Ошибка не в формате контракта
- **WHEN** сервер отвечает на ошибку телом `{"detail": ...}`
- **THEN** тест падает, даже если статус верный
### 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/`
### 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: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
«Ключ после срока».
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL и Valkey, применить
миграции;
- запустить два 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` удаляет их и начинает заново