Files
mtusi2026lab4/openspec/specs/student-tests/spec.md
T

34 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: «Сбой при записи сообщения», «Отказ БД при отправке», «Ключ после срока»;
  • api-conventions: «Лимит одновременных загрузок»;
  • attachments: «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место освобождается», «Медленный клиент», «Медленная передача в срок», «Потерянный оригинал»;
  • storage-consistency: все сценарии.

Команда SHALL:

  • собрать образ из рабочего дерева;
  • поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить миграции и bootstrap S3;
  • запустить три API:
    • с настройками по умолчанию;
    • «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом из одного соединения;
    • «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в очереди, коротким сроком ожидания места и коротким сроком тела. Их значения SHALL передаваться проверкам;
  • запустить уборщика с коротким grace и интервалом, сравнимыми со временем теста, без плановой сверки, и передать их значения проверкам. Grace при этом SHALL проходить проверку границы живой загрузки (service-configuration, «Параметры уборщика»). Сверку проверки запускают сами, и плановая сверка не меняет стенд у них за спиной;
  • выполнить проверки отказов;
  • удалить стенд вместе с его данными при любом исходе.

Hook стенда отказов SHALL уметь:

  • сообщить вложения стенда в PostgreSQL с их статусами, id последнего вложения в статусе «загружается» и id вложений с потерянным оригиналом;
  • сообщить, у каких вложений есть объект в bucket стенда, — по самим объектам, а не по каталогам хранилища;
  • внедрить отказ PostgreSQL:
    • при записи метаданных загрузки с заданным filename;
    • при фиксации её ready, и задержать такую фиксацию;
    • при пометке потерянного оригинала такого вложения;
  • убить и снова запустить обычный API стенда;
  • внести расхождения хранилищ:
    • записать объект в bucket стенда мимо API и удалить объект мимо API — только под префиксом вложений базы стенда;
    • удалить метаданные вложения, изменить в них размер и сдвинуть их время в прошлое;
  • выполнить разовую сверку — без изменений или с --apply, с заданным пределом изменений — и вернуть её записи и код выхода;
  • остановить и запустить уборщика стенда, а также запустить отдельного уборщика с коротким интервалом плановой сверки на заданное время и вернуть его журнал.

Других сведений о хранилищах проверки вложений не получают. Объекты без метаданных проверка находит сравнением двух списков: вложений и объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо 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 код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён