component-tests

name

component-tests

description

Генерация, ревью и расширение компонентных тестов программы — сетевого сервиса (OpenAPI/AsyncAPI) или CLI-инструмента (api-specification/cli.md + report.schema.json) — как чёрного ящика. Применять, когда нужно создать новые .feature, дополнить существующие, добавить тестовые данные/фикстуры или оценить набор на полноту покрытия контракта и режимов отказа. Не применять для юнит-тестов или контрактных тестов между сервисами.

Компонентные тесты — спецификация чёрного ящика

Skill для генерации компонентных тестов программы — сетевого сервиса или CLI-инструмента. Тест — это исполняемая спецификация: что программа обещает делать на штатном пути и при отказе каждой внешней связи. Не охота за багами и не покрытие кода.

Объект — спецификация программы, не привязка к инструментам

Тестируем программу как чёрный ящик в изоляции — сетевой сервис или CLI-инструмент, безразлично. Это общий инженерный подход, не зависящий от языка и фреймворка: задача одна — проверить спецификацию интерфейса программы (контракт), а не её внутренности. Для сервиса контракт — OpenAPI/AsyncAPI и внешние входы это эндпоинты/события; для CLI-тула контракт — cli.md + report.schema.json, а внешние входы — подкоманды.

Изоляция реализуется единообразно: вся среда поднимается в Docker Compose. Для сервиса — сам сервис плюс его зависимости. Для CLI-тула — бинарь в контейнере (запускается как одноразовый сервис compose против фикстур) плюс его внешние зависимости как сервисы compose, включая заглушку внешнего API (например, LLM-эндпоинта), к которой тул обращается по имени сервиса. Заглушка — полноценный сервис, отвечающий по реальному протоколу, а не in-code мок.

Выбор среды не пересматриваем: компонентные тесты — всегда в Docker Compose.

Принцип: контракт первичен

Компонентные тесты пишутся до кода сервиса (TDD-цикл). Значит, режимы отказа интеграций должны быть зафиксированы в контрактах, не выведены из кода адаптеров. Код — следствие контракта, не источник.

Источники режимов отказа в порядке приоритета:

1. OpenAPI (api-specification/openapi.yaml) — для синхронных эндпоинтов. Все 5xx-ответы с разбиением по error.code.

2. README раздел «Карта режимов отказа» — для асинхронных интеграций и любых интеграций, не описанных через коды HTTP.

3. Fallback: код адаптера — если контракт ещё не детализирован. Создать TODO в backlog.md: «зафиксировать режимы отказа в контракте».

Граница со слоем юнитов

Компонент-тесты проверяют обещания интерфейса наружу: коды возврата, поля отчёта по схеме, реакцию на каждый различимый режим отказа интеграции. Они не воспроизводят бизнес-логику — её доказывают юниты в internal/.

Перед тем как добавить фикстуру или сценарий, ответь:

Какую новую ветку контракта он триггерит — новый error.code, новое значение exit, новое значение layers.Ln.status / jtbd.*.status, новое поле отчёта, новый формат вывода, новый флаг CLI?

Если ни одну — это юнит-уровень, не добавляй. «Покрыть L1-логику глубже» или «больше плохих ссылок» не считается: контракт не различает «одна битая ссылка» и «десять», он различает «есть blocker / нет blocker». Для каждой ветки контракта достаточно минимальной фикстуры, которая её триггерит.

Лишние сценарии — удалять. Если ревью показывает, что сценарий не триггерит новую ветку контракта (дубль, юнит-уровень, «на всякий случай») — его нужно удалить, а не оставить «про запас». Число сценариев должно точно соответствовать формуле: N = N_подкоманд + Σ режимы_отказа. Сценарии сверх формулы — признак неточного понимания границы со слоем юнитов.

Модель фикстур: изолированные на слайс

Каждый слайс имеет собственный набор фикстур — repo-good-<slice> и repo-bad-<slice>. Фикстуры между слайсами не разделяются.

Почему не shared-фикстуры. Разделяемая repo-good накапливает инвариант всех зарегистрированных check-типов одновременно: добавился новый слайс → старая фикстура может перестать быть «хорошей» для нового check-а. Это нарушает независимость слайсов и создаёт скрытую связность: изменение в фикстуре одного слайса ломает тесты другого. Изолированные фикстуры этого лишены.

Исключение — assess. Подкоманда assess запускает все слои сразу, поэтому её фикстура (repo-good-assess, repo-bad-assess) по определению покрывает все check-типы. Но это отдельная фикстура, спроектированная специально для assess, а не переиспользование фикстур других слайсов.

Минимальность фикстуры. Фикстура каждого слайса содержит ровно то, что нужно для триггера одной ветки контракта, — не больше. Лишний контент в repo-bad-<slice> делает failure-сценарий нечитаемым: непонятно, какой именно check сработал.

Проектирование фикстуры нового слайса

Перед написанием .feature — спроектируй фикстуру:

1. repo-good-<slice>: минимальный репозиторий, в котором новый check не производит нарушений. Только тот контент, который нужен для happy-path. Никакого «реалистичного» наполнения сверх необходимого.
2. repo-bad-<slice>: добавь к minimal-базе ровно один элемент, триггерящий нужную ветку отказа. Один элемент — одна ветка.
3. Для каждой дополнительной ветки отказа — отдельный вариант repo-bad или отдельный параметр (если степы это поддерживают).

Этот шаг выполняется до написания сценариев и до кода — он часть дизайна, не отладки реализации.

Формула

N_тестов = N_эндпоинтов_API + Σ (число различимых режимов отказа интеграции i)

• N_эндпоинтов_API — количество эндпоинтов в OpenAPI плюс количество событий (publish и subscribe) в AsyncAPI; для CLI-тула — количество подкоманд.

• Различимый режим отказа — каждый отдельный тип ошибки, который сервис обещает наружу для данной интеграции.

Что считать интеграцией

Интеграция — это выход за процесс сервиса:

• сеть (HTTP, gRPC, очереди, БД через драйвер);
• файловая система;
• IPC (Inter-Process Communication, межпроцессное взаимодействие).

Локальные библиотеки в памяти процесса — модули, не интеграции.

Алгоритм генерации тестов

Шаг 0. Спроектировать режимы отказа и подготовить раннер (если ещё не сделано).

Перед тем как писать .feature, должны существовать:

1. 5xx-ответы с error.code в OpenAPI на каждый различимый режим отказа.
2. Таблица «Карта режимов отказа» в README с тем же набором.
3. Раннер компонентных тестов (godog/cucumber/...) с docker-compose, набором базовых степов (HTTP, доменная авторизация, фикстуры режимов отказа интеграций) и хотя бы одним smoke-сценарием.

Без любого из трёх Шаг 1 проваливается: либо нечего проверять, либо нечем проверять.

Промпт для агента (лаконичный, самодостаточный):

Прочитай README раздел «Стек» и определи интеграции сервиса (правило: интеграция = выход за процесс — сеть, ФС, IPC). Для каждой интеграции перечисли теоретически возможные режимы отказа. Объедини в один error.code те режимы, на которые клиент и ops реагируют одинаково; разнеси по разным кодам те, у которых поведение различается (HTTP-код, Retry-After, эскалация оператору). Зафиксируй результат: в OpenAPI — 5xx-ответы с примерами error.code для каждого различимого режима (разные HTTP-коды — разные responses); в README — таблица «Карта режимов отказа» с теми же строками и колонкой «поведение клиента». Решение «почему именно столько режимов» — в docs/adr/.

Правило различения: режим — отдельный, если хотя бы одно из четырёх различается между ним и другими режимами интеграции:

• HTTP-статус (503 vs 507 vs 500);
• заголовки ответа (Retry-After есть/нет);
• действие клиента (ретраить / не ретраить / ретраить с backoff);
• действие оператора (ничего / alert / эскалация).

Если все четыре одинаковы — режимы сворачиваются в один error.code.

Минимум, что должно остаться после Шага 0:

• секция components/responses в OpenAPI содержит общий ответ на отказ интеграции (например, ServiceUnavailable) с примером error.code для каждого различимого режима;
• каждый эндпоинт в responses ссылается на этот общий ответ;
• в README таблица «Карта режимов отказа» содержит ровно те же строки, что и error.code-примеры в OpenAPI.

Шаг 1. Прочитать api-specification/openapi.yaml. Перечислить эндпоинты. Если есть asyncapi.yaml — перечислить события.

Шаг 2. На каждый эндпоинт и каждое событие — один happy-path сценарий. Не склеивать фазы двухфазного протокола (например, регистрация: challenge + attestation) в один сценарий — это два отдельных контракта.

Шаг 3. Определить режимы отказа из контрактов:

• синхронные: все 5xx из OpenAPI с разбивкой по error.code;
• асинхронные: строки таблицы «Карта режимов отказа» из README;
• fallback: код адаптера + TODO в backlog.md.

Шаг 4. На каждый режим отказа — один сценарий.

Шаг 5. Сверить: N = N_эндпоинтов + N_событий + Σ режимы отказа.

Ревью и расширение существующих тестов

Когда задача — не «написать с нуля», а «доработать тестовые данные / тесты» или «оценить покрытие», направление обхода инвертируется: ходи от контракта вниз к данным, не от данных вверх к гипотезам «чего бы ещё добавить».

Алгоритм ревью:

1. Выпиши пункты контракта — подкоманды/эндпоинты, поля отчёта по схеме, значения exit, флаги CLI, строки «Карты режимов отказа».
2. Для каждого пункта найди сценарий, который его триггерит. Если нет — это пробел, кандидат на новый сценарий или фикстуру.
3. Для каждого существующего сценария примени диагностический вопрос из «Границы со слоем юнитов». Если он не покрывает новую ветку контракта — он либо дубль, либо юнит-уровень, либо ложно-полезная «отладочная» ассерция (например, проверка конкретного violation.code вместо severity=blocker).

Типовой источник дрейфа на ревью — мышление «больше данных = лучше». Больше данных полезно только если они открывают новую ветку контракта. Узкие фикстуры «под один слой» имеют смысл, только если контракт обещает что-то, что широкая фикстура триггернуть не может (например, assess --up-to со status="skipped" требует фикстуру, ломающую ранний слой и не ломающую поздний — это контрактная необходимость, не желание глубины).

Структура файлов

• Один .feature файл на ресурс API.
• Имя файла = имя ресурса в нижнем регистре.
• Расположение: component-tests/<resource>.feature.

Что НЕ делать

• Не выводить режимы отказа из кода как основной путь.
• Не генерировать сценарии валидации полей запроса (юнит-уровень).
• Не повторять бизнес-логику (доказана юнитами) — см. «Граница со слоем юнитов».
• Не писать smoke-test на запуск (контролирует компилятор).
• Не добавлять сценарии «на всякий случай».
• Не склеивать фазы протокола в один сценарий.

Запуск

Все компонентные тесты запускаются в Docker Compose с реальными зависимостями — и для сервиса, и для CLI-тула (бинарь в контейнере как сервис compose). Тест дёргает настоящий интерфейс программы: HTTP-эндпоинт сервиса или подкоманду тула. Внешний API замещается заглушкой-сервисом в том же compose, отвечающей по реальному протоколу. Никаких in-code моков.

Чек-лист перед коммитом

1. Шаг 0 пройден: интеграции и режимы отказа зафиксированы в OpenAPI и README.
2. Карта режимов отказа в README заполнена и актуальна.
3. Число .feature файлов = число ресурсов в API.
4. Число happy-path сценариев = число эндпоинтов + число событий.
5. Число сценариев отказа = сумма режимов отказа из OpenAPI и README.
6. Все сценарии запускаются в Docker Compose с реальными зависимостями.
7. Нет валидации полей, бизнес-логики, smoke-тестов.
8. Фикстуры изолированы на слайс — repo-good-<slice> и repo-bad-<slice>. Фикстуры других слайсов не используются. Фикстура assess — отдельная.
9. Число сценариев = формула — лишние удалены; каждый сценарий триггерит ровно одну ветку контракта, которой без него не было.

Чек-лист шаблона (Шаг 0) перед хендоффом другому агенту

Дополнительно к чек-листу выше — если на этом шаге готовится шаблон тестов (раннер, базовые степы, compose), который потом получит другой агент или разработчик для написания .feature-файлов:

1. Каждый степ из steps/*.go вызван хотя бы раз из features/smoke.feature. Не из Go-кода (макрошага), а именно из Gherkin — там другая семантика аргументов и парсинга. Степы, написанные «в голове через Go-вызов», часто проваливаются при первой же попытке вызвать их из .feature (например, динамический id, который в Gherkin-строке статически не зафиксировать).
2. Smoke зелёный — full pipeline (docker compose build → up → run).
3. README шаблона перечисляет все степы с их регулярками. Если степ нельзя выразить одной фразой — это сигнал переименовать или разнести.
4. Включены степы для типовых случаев API: точное равенство JSON-поля, присутствие поля, непустое поле (для динамических значений вроде токенов и timestamp). Без них первый же endpoint с JWT упрётся в стену.

Пример: passkey-demo-api

• 6 эндпоинтов в OpenAPI (двухфазная регистрация, двухфазный вход, выход, /users/me).
• 1 интеграция — SQLite.
• 2 различимых режима отказа SQLite:
  • db_locked (503 + Retry-After) — SQLITE_BUSY, lock contention;
  • db_disk_full (507) — диск переполнен на запись.
• AsyncAPI нет.

N_тестов = 6 + 2 = 8. Восемь компонентных сценариев — полная спецификация сервиса как чёрного ящика.

Замечание: db_unavailable намеренно не выделен — для встроенной SQLite это синтетический режим. Если бы интеграция была сетевой (Postgres, MySQL) — добавили бы. Принцип: в спеку идут только реально воспроизводимые в тестах режимы, не теоретические.