Skip to content

BASE_CHECKS.md

Latest commit

 

History

History
49 lines (41 loc) · 6.69 KB

BASE_CHECKS.md

File metadata and controls

49 lines (41 loc) · 6.69 KB
Raw

Базовые проверки для каждой ручки API

Этот файл — контракт на автотесты. Навыки /onboard-api и /add-endpoint читают его и покрывают каждую ручку всеми применимыми проверками. Файл можно свободно править: добавлять, менять и удалять пункты. Агент следует текущей версии.

Статусы и коды ошибок доступа и валидации берутся из профиля config/api.json (access, validation), поэтому чек-лист одинаков для любого API.

Как редактировать

  • Каждая проверка — строка таблицы с уникальным ID (BC-NN). Новые ID добавляйте в конец, старые не переиспользуйте.
  • Способ:
    • auto — генерируется из swagger, профиля и project/knowledge.py для всех ручек сразу (tests/api/test_auto_base.py). Руками для новой ручки её писать не нужно, достаточно карточки в knowledge.py.
    • manual — агент пишет тест руками в tests/api/test_<группа>.py для каждой ручки.
    • report — проверяется отчётом о покрытии в конце прогона (./api run, секция «Покрытие ручек»).
  • Хотите, чтобы новая проверка стала автоматической, — поставьте auto и попросите агента доработать autogen.py.
  • Проверку можно пропустить для ручки, только если её условие «Когда» не выполняется. Причина попадает в отчёт агента.
  • Чтобы применить новую проверку к уже существующим ручкам, попросите «примени BC-NN ко всем ручкам».

Проверки

ID Проверка Когда Ожидание Способ
BC-01 Формат ответа всегда обёртка по профилю (response.*: признак успеха, correlationId), время ответа < slowResponseMs auto — встроено в ok()/err() каждого теста
BC-02 Позитивный сценарий всегда основной вызов валидными данными → 2xx; набор полей ответа совпадает с ожидаемым (*_KEYS в project_fixtures.py); значения из запроса вернулись в ответе manual + report
BC-03 Без авторизации access ≠ public access.missingToken (обычно 401) auto
BC-04 Невалидный токен access ≠ public access.invalidToken (обычно 401) auto
BC-05 Недопущенные роли уровень закрыт от части ролей access.denied (обычно 403) с кодом уровня из access.denied.codes auto
BC-06 Обязательные поля тела в схеме есть required без каждого поля по отдельности → validation (статус, код, поле в тексте по fieldInMessage) auto
BC-07 Типы полей тела есть тело неверный тип каждого поля → validation auto
BC-08 Ограничения полей тела есть min/max, minLength/maxLength, pattern, enum, exclusiveMinimum/Maximum значение за границей → validation auto
BC-09 Query-параметры есть query-параметры с типом, границами или enum неверный тип, выход за границу, не из enum → validation auto
BC-10 Несуществующий ресурс в пути есть id ресурса несуществующий id → 404 с кодом «не найдено» manual
BC-11 Бизнес-ошибки у ручки есть коды в errors (knowledge.py) по тесту на каждый код; невоспроизводимые через API — в untestable с причиной manual + report
BC-12 Побочные эффекты ручка меняет данные изменение видно через GET этого ресурса и в связанных сущностях (суммы, остатки, статусы, история) manual
BC-13 Изоляция данных ручка работает с данными конкретного пользователя чужой ресурс недоступен (обычно 404 или 403 — как описано в api-notes) manual
BC-14 Повтор и дубликаты ручка создаёт ресурс с уникальным ключом или меняет статус дубль → 409; повторный недопустимый переход → 409 (или как описано в api-notes) manual
BC-15 Граничные валидные значения у ключевых полей есть границы минимум и максимум принимаются (2xx) manual
BC-16 Расхождения со swagger и баги фактическое поведение отличается от swagger или ожиданий тест описывает правильное поведение, @pytest.mark.known_bug + xfail(strict=True), запись в knowledge/api-audit-*.md; для автокейса — skipAuto в карточке с причиной manual

Правила оформления тестов

  • Данные — только из фикстур (actors[role], new_user(role), фикстуры сущностей из project_fixtures.py). Тест не зависит от других тестов и порядка запуска.
  • Проверка ответа — через ok(r) и err(r, status, code).
  • Ручные проверки лежат в tests/api/test_<группа>.py (группа = tag в swagger), в классе по смыслу (TestCreate, TestRead, ...). Название теста говорит, что проверяется: test_duplicate_email_409.
  • Один кейс — одна причина падения. Для наборов значений — @pytest.mark.parametrize с понятными ids.