The change moves to openspec/changes/archive/2026-10-13-fix-known-issues. Its delta requirements join the main specs: graceful-shutdown "Остановка во время старта", load-benchmark "События Docker профилей отказа и замены", student-tests "Доказательства исключений сверки в репозитории" and "PostgreSQL стенда отказов без аварийных перезапусков". AGENTS and REPORT now say all eight lab 3 changes are archived and none is active. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
26 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.
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на повтор
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_<db>, ни тестового контейнера после команды нет, число строк в таблицах рабочей базы не изменилось, а рабочий стенд продолжает отвечать через балансировщик
Scenario: Упавшие тесты
- WHEN во время
make test_isolatedпадает хотя бы один тест - THEN код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база
test_<db>удалена
Scenario: Прерывание
- WHEN
make test_isolatedпрерван Ctrl+C - THEN тестовый контейнер остановлен и удалён, база
test_<db>удалена
Scenario: Хвост прошлого прогона
- WHEN тестовый контейнер или база
test_<db>остались от прогона, убитого без уборки - THEN следующий
make test_isolatedудаляет их и начинает заново
Scenario: Сохранить базу для разбора
- WHEN выполнен
make test_isolated KEEP_TEST_DB=1 - THEN после прогона тестовый контейнер удалён, база
test_<db>остаётся, а команда печатает её имя
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удаляет их и начинает заново
Requirement: Доказательства исключений сверки в репозитории
Если способ проверки сценария из списка исключений сверки покрытия
ссылается на файл в evidence/, этот файл SHALL лежать в репозитории
текущей лабы. В нём SHALL быть результат, снятый на стенде этой лабы,
команда, дата и commit. Если способ проверки — команда, которая сама
снимает доказательство на стенде, исключение SHALL её называть.
Сверка покрытия SHALL падать, если файла по ссылке исключения нет, и называть сценарий и путь.
Такое доказательство MUST NOT содержать токенов, паролей и их хэшей целиком — только факты, счётчики и префиксы.
Scenario: Ссылка на отсутствующий файл
- WHEN исключение ссылается на файл
evidence/…, которого нет в репозитории - THEN
make student_testзавершается с ненулевым кодом, а сообщение называет сценарий и путь
Scenario: Кэш и хранение секретов на стенде лабы
- WHEN проверяющий открывает файлы, на которые ссылаются исключения
chat-cache«Чтение из кэша», «Срок записи», «Временная база»,sessions«Токена нет в хранилище» иusers«Хэш в БД» - THEN в них вывод названной в исключении команды на стенде с балансировщиком и двумя репликами, дата и commit, а токенов, паролей и полных хэшей нет
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 код выхода команды ненулевой, найденные строки журнала выведены, а стенд отказов удалён