Files
mtusi2026lab4/openspec/specs/student-tests/spec.md
T
ricoromaandClaude Opus 5.5 5b42bd2891 feat: compensate failed uploads and clean stale pending attachments
- 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>
2026-10-21 06:10:37 +03:00

31 KiB
Raw Blame History

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_<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_checks PostgreSQL стенда отказов перезапустился аварийно
  • THEN код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён