- upload: delete the stored object when ready fails before COMMIT or the pending row is gone (503 instead of 500); unknown COMMIT outcome keeps it - cleaner service (python -m src.cleaner): stale pending rows older than grace (900 s, must exceed 17 s live-upload bound) under FOR UPDATE SKIP LOCKED, object before row, own S3 user with read/delete only - shared session_scope for API and cleaner; early_stop process name - partial index on pending attachments, CREATE INDEX CONCURRENTLY - s3-bootstrap: cleaner user, policy and checks; make env_setup appends missing template variables to an existing .env - failure checks: cleaner on the failure stand, id-list hook actions, five new and three updated tests; driver upload-consistency - sync upload-consistency deltas into main specs (storage-consistency) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
31 KiB
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 с
codeinvalid_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_cursornull
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 по порядку:
- поднять PostgreSQL, Valkey и S3 с bootstrap;
- собрать образ и создать базу заново;
- применить к ней миграции сервисом миграций compose;
- запустить отдельный контейнер API из определения сервиса compose, в
котором подменено только имя базы, и опубликовать его на
127.0.0.1:TEST_APP_PORTиз.env; - дождаться готовности и выполнить публичный smoke (
make test) и весь набор (make student_test) против этого контейнера; - остановить и удалить контейнер, удалить базу и объекты S3 под
префиксом
test_<db>/.
Это один процесс 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_<db>, ни тестового контейнера, ни объектов под префиксомtest_<db>/после команды нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились, а рабочий стенд продолжает отвечать через балансировщик
Scenario: Упавшие тесты
- WHEN во время
make test_isolatedпадает хотя бы один тест - THEN код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база
test_<db>и объекты под префиксомtest_<db>/удалены
Scenario: Прерывание
- WHEN
make test_isolatedпрерван Ctrl+C - THEN тестовый контейнер остановлен и удалён, база
test_<db>и объекты под префиксомtest_<db>/удалены
Scenario: Хвост прошлого прогона
- WHEN тестовый контейнер, база
test_<db>или объекты под префиксомtest_<db>/остались от прогона, убитого без уборки - THEN следующий
make test_isolatedудаляет их и начинает заново
Scenario: Сохранить базу для разбора
- WHEN выполнен
make test_isolated KEEP_TEST_DB=1 - THEN после прогона тестовый контейнер удалён, база
test_<db>и объекты под префиксомtest_<db>/остаются, а команда печатает имя базы и префикс
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_checksPostgreSQL стенда отказов перезапустился аварийно - THEN код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён