# 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. С лабы 4 к ним SHALL добавиться слишком большой файл, повреждённое изображение, подмена MIME, чужое `attachment_id` и вложение другого чата. Каждый такой тест SHALL проверять, что ошибка клиента дала статус 4xx в формате контракта, а не 500. #### 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` на повтор #### Scenario: Слишком большой файл в рубрике - **WHEN** участник загружает файл больше 10 MiB с `Content-Length` и частями без него - **THEN** проверяется ответ 413 `payload_too_large` в обоих случаях #### Scenario: Повреждённое изображение в рубрике - **WHEN** участник загружает обрезанные PNG и JPEG и PNG с изменённым байтом данных - **THEN** проверяется ответ 415 `unsupported_media_type` на каждый #### Scenario: Подмена MIME в рубрике - **WHEN** участник загружает JPEG с `Content-Type: image/png` и текст с `Content-Type: image/jpeg` - **THEN** проверяется ответ 415 `unsupported_media_type` на оба #### Scenario: Чужое attachment_id в рубрике - **WHEN** участник отправляет сообщение с вложением чата, где он не состоит, и с неизвестным id вложения, а посторонний читает метаданные и байты вложения - **THEN** проверяется ответ 404 `not_found` на каждый запрос #### Scenario: Вложение другого чата в рубрике - **WHEN** участник двух чатов отправляет в один из них сообщение с вложением другого - **THEN** проверяется ответ 404 `not_found`, и сообщение не появляется в истории ### 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` и с лабы 4 `attachments` и `storage-consistency`, который воспроизводится по 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, а с лабы 4 — негативные тесты вложений и проверки отказов S3. #### Scenario: Доказательство в отчёте - **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md` - **THEN** в ней есть команда, наблюдаемый результат и путь к файлу вывода в `evidence/` ### Requirement: Прогон на временной базе `make test_isolated` SHALL проверять образ, собранный из рабочего дерева, в связке compose на временной базе `test_<имя рабочей базы>` в PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по порядку: 1. поднять PostgreSQL, Valkey и S3 с bootstrap; 2. собрать образ и создать базу заново; 3. применить к ней миграции сервисом миграций compose; 4. запустить отдельный контейнер API из определения сервиса compose, в котором подменено только имя базы, и опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`; 5. дождаться готовности и выполнить публичный smoke (`make test`) и весь набор (`make student_test`) против этого контейнера; 6. остановить и удалить контейнер, удалить базу и объекты S3 под префиксом `test_/`. Это один процесс API без балансировщика: набор SHALL запускаться с `EXPECT_REPLICAS=1`, и тесты реплик пропускаются с причиной. Код выхода SHALL быть ненулевым, если не прошёл smoke, набор или уборка. Рабочая база и рабочие контейнеры стенда MUST NOT затрагиваться. Тестовый прогон отделён от рабочего именем базы: - карточки чатов в Valkey — именем базы в ключе (capability `chat-cache`); - объекты в S3 — префиксом имени базы в ключе объекта (capability `object-storage`). Объекты рабочей базы при уборке MUST NOT удаляться. Параллельный запуск двух прогонов не поддерживается. #### Scenario: Успешный прогон - **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и выполнен `make test_isolated` - **THEN** smoke и набор прошли, тесты реплик пропущены с причиной, код выхода 0, ни базы `test_`, ни тестового контейнера, ни объектов под префиксом `test_/` после команды нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились, а рабочий стенд продолжает отвечать через балансировщик #### Scenario: Упавшие тесты - **WHEN** во время `make test_isolated` падает хотя бы один тест - **THEN** код выхода ненулевой, журнал тестового контейнера выведен, контейнер удалён, база `test_` и объекты под префиксом `test_/` удалены #### Scenario: Прерывание - **WHEN** `make test_isolated` прерван Ctrl+C - **THEN** тестовый контейнер остановлен и удалён, база `test_` и объекты под префиксом `test_/` удалены #### Scenario: Хвост прошлого прогона - **WHEN** тестовый контейнер, база `test_` или объекты под префиксом `test_/` остались от прогона, убитого без уборки - **THEN** следующий `make test_isolated` удаляет их и начинает заново #### Scenario: Сохранить базу для разбора - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` - **THEN** после прогона тестовый контейнер удалён, база `test_` и объекты под префиксом `test_/` остаются, а команда печатает имя базы и префикс ### Requirement: Проверки отказов на отдельном стенде Сценарии отказов SHALL проверяться автоматически одной командой `make failure_checks`: - `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при запросе с токеном»; - `data-storage`: «Сбой при добавлении участников», «БД остановлена», «БД вернулась», «Соединения исчерпаны»; - `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище объектов недоступно»; - `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», «Очистка кэша»; - `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке», «Ключ после срока»; - `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв передачи тела»; - `storage-consistency`: все сценарии. Команда SHALL: - собрать образ из рабочего дерева; - поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить миграции и bootstrap S3; - запустить два API: с настройками по умолчанию и «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом из одного соединения; - запустить уборщика с коротким grace и интервалом, сравнимыми со временем теста, и передать их значения проверкам. Grace при этом SHALL проходить проверку границы живой загрузки (`service- configuration`, «Параметры уборщика»); - выполнить проверки отказов; - удалить стенд вместе с его данными при любом исходе. Hook стенда отказов SHALL уметь: - сообщить вложения стенда в PostgreSQL с их статусами и `id` последнего вложения в статусе «загружается»; - сообщить, у каких вложений есть объект в bucket стенда, — по самим объектам, а не по каталогам хранилища; - внедрить отказ PostgreSQL при записи метаданных и при фиксации `ready` загрузки с заданным `filename` и задержать такую фиксацию; - убить и снова запустить обычный API стенда. Других сведений о хранилищах проверки вложений не получают. Объекты без метаданных проверка находит сравнением этих двух списков. Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш, хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка. Параллельный запуск двух прогонов не поддерживается: уборка хвоста в начале второго удаляет стенд первого. #### Scenario: Успешный прогон - **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` - **THEN** все проверки отказов прошли, код выхода 0, контейнеров и volumes стенда отказов после команды нет, а у контейнеров рабочего стенда прежнее время старта, и рабочий API отвечает #### Scenario: Упавшая проверка - **WHEN** во время `make failure_checks` падает хотя бы одна проверка - **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов выведены, стенд отказов удалён #### Scenario: Прерывание - **WHEN** `make failure_checks` прерван Ctrl+C - **THEN** стенд отказов остановлен и удалён вместе с volumes #### Scenario: Хвост прошлого прогона - **WHEN** контейнеры или volumes стенда отказов остались от прогона, убитого без уборки - **THEN** следующий `make failure_checks` удаляет их и начинает заново ### Requirement: Доказательства исключений сверки в репозитории Если способ проверки сценария из списка исключений сверки покрытия ссылается на файл в `evidence/`, этот файл SHALL лежать в репозитории текущей лабы. В нём SHALL быть результат, снятый на стенде этой лабы, команда, дата и commit. Если способ проверки — команда, которая сама снимает доказательство на стенде, исключение SHALL её называть. Сверка покрытия SHALL падать, если файла по ссылке исключения нет, и называть сценарий и путь. Такое доказательство MUST NOT содержать токенов, паролей и их хэшей целиком, ключей доступа и секретов S3 — только факты, счётчики и префиксы. #### Scenario: Ссылка на отсутствующий файл - **WHEN** исключение ссылается на файл `evidence/…`, которого нет в репозитории - **THEN** `make student_test` завершается с ненулевым кодом, а сообщение называет сценарий и путь #### Scenario: Кэш и хранение секретов на стенде лабы - **WHEN** проверяющий открывает файлы, на которые ссылаются исключения `chat-cache` «Чтение из кэша», «Срок записи», «Временная база», `sessions` «Токена нет в хранилище» и `users` «Хэш в БД» - **THEN** в них вывод названной в исключении команды на стенде с балансировщиком и двумя репликами, дата и commit, а токенов, паролей и полных хэшей нет #### Scenario: Вложения на стенде лабы - **WHEN** проверяющий открывает файлы, на которые ссылаются исключения `attachments` «Принявшая реплика остановлена», «Байты не в БД и не на диске API» и «Рестарт стенда» - **THEN** в них вывод названной в исключении команды на стенде с балансировщиком, двумя репликами и S3, дата и commit, SHA-256 загруженного и скачанного файла, а токенов и секретов S3 нет ### Requirement: PostgreSQL стенда отказов без аварийных перезапусков Проверки отказов MUST NOT приводить к аварийному перезапуску PostgreSQL своего стенда. Процессы, которые проверки запускают в его контейнере (сессии `psql`, занимающие слоты соединений), после завершения MUST NOT восприниматься сервером PostgreSQL как его собственные процессы. `make failure_checks` SHALL после проверок и до уборки читать журнал PostgreSQL стенда отказов и искать признаки аварийного перезапуска: - неизвестный дочерний процесс сервера; - завершение всех процессов сервера и повторная инициализация; - восстановление после сбоя. Сводку журнала команда SHALL печатать после каждого прогона проверок, с признаками и без. Если признаки есть, команда SHALL выводить найденные строки и завершаться с ненулевым кодом. #### Scenario: Заполнение и освобождение слотов - **WHEN** проверка «Соединения исчерпаны» заняла все слоты соединений PostgreSQL стенда отказов, а затем освободила их - **THEN** в журнале PostgreSQL стенда нет «untracked child process» и «reinitializing», а сводка журнала в выводе команды называет ноль признаков аварии #### Scenario: PostgreSQL перезапустился аварийно - **WHEN** во время `make failure_checks` PostgreSQL стенда отказов перезапустился аварийно - **THEN** код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён