# 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_`, ни тестового контейнера после команды нет, число строк в таблицах рабочей базы не изменилось, а рабочий стенд продолжает отвечать через балансировщик #### Scenario: Упавшие тесты - **WHEN** во время `make test_isolated` падает хотя бы один тест - **THEN** код выхода ненулевой, журнал тестового контейнера выведен, контейнер удалён, база `test_` удалена #### Scenario: Прерывание - **WHEN** `make test_isolated` прерван Ctrl+C - **THEN** тестовый контейнер остановлен и удалён, база `test_` удалена #### Scenario: Хвост прошлого прогона - **WHEN** тестовый контейнер или база `test_` остались от прогона, убитого без уборки - **THEN** следующий `make test_isolated` удаляет их и начинает заново #### Scenario: Сохранить базу для разбора - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` - **THEN** после прогона тестовый контейнер удалён, база `test_` остаётся, а команда печатает её имя ### 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` удаляет их и начинает заново