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>
358 lines
22 KiB
Markdown
358 lines
22 KiB
Markdown
# 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` удаляет их и начинает заново
|