Initialize project scaffold and domain model

2026-03-25 12:20:42 +03:00
commit fb302b2a2c
51 changed files with 6815 additions and 0 deletions
@@ -0,0 +1,131 @@
+# Стратегия тестирования
+
+## 1. Назначение документа
+
+Этот документ фиксирует, как проект должен тестироваться с самого начала разработки, чтобы архитектура не осталась "только на бумаге".
+
+Цель:
+
+- проверять доменную модель отдельно от транспорта;
+- ловить регрессии в mapping;
+- не дать адаптерам начать вести себя по-разному;
+- обеспечить воспроизводимость для дипломной демонстрации.
+
+## 2. Уровни тестов
+
+### 2.1. Unit tests
+
+Покрывают:
+
+- `mcpaas-schema`
+- `mcpaas-mapping`
+- `mcpaas-proto`
+- небольшие части `mcpaas-core`
+
+Что проверять:
+
+- валидацию схем;
+- `JSONPath` parsing;
+- применение input/output mapping;
+- генерацию чернового mapping;
+- protobuf -> schema normalization;
+- JSON -> protobuf и protobuf -> JSON conversion.
+
+### 2.2. Integration tests
+
+Покрывают:
+
+- `mcpaas-registry` с реальной БД;
+- `mcpaas-runtime` с реальными adapter contracts;
+- `admin-api` на поднятом приложении;
+- publish flow и YAML import/export.
+
+Что проверять:
+
+- создание operation и новой version;
+- publish и reload published tools;
+- тестовый вызов draft;
+- экспорт в YAML и повторный импорт;
+- связность БД между `operations`, `operation_versions`, `published_operations`.
+
+### 2.3. Adapter tests
+
+Отдельно для каждого протокола:
+
+- REST adapter;
+- GraphQL adapter;
+- gRPC unary adapter.
+
+Что проверять:
+
+- сборку request;
+- нормализацию response;
+- обработку ошибок;
+- стабильность mapping context.
+
+### 2.4. End-to-end tests
+
+Минимально нужны сценарии:
+
+- создать REST operation -> протестировать -> опубликовать -> вызвать как MCP tool;
+- создать GraphQL operation -> протестировать -> опубликовать -> вызвать как MCP tool;
+- загрузить `.proto` или descriptor set -> создать gRPC unary operation -> протестировать -> опубликовать -> вызвать как MCP tool.
+
+## 3. Что должно быть покрыто обязательно
+
+### Обязательно с первого этапа
+
+- schema validation;
+- mapping execution;
+- YAML import/export roundtrip;
+- versioning logic registry;
+- publish flow.
+
+### Обязательно до первого демо
+
+- хотя бы один end-to-end сценарий для каждого из трех протоколов;
+- negative tests на invalid `JSONPath`;
+- negative tests на invalid protobuf descriptor;
+- negative tests на GraphQL errors при HTTP `200`.
+
+## 4. Формат тестовых данных
+
+Рекомендуется использовать:
+
+- JSON fixtures для sample input/output;
+- YAML golden files для export/import;
+- `.proto` и descriptor fixtures для gRPC;
+- snapshot tests для generated draft.
+
+## 5. Техническая стратегия
+
+Для Rust-части:
+
+- unit/integration tests через `cargo test`;
+- тестовые фикстуры в `tests/fixtures/`;
+- golden files для YAML;
+- отдельные integration suites для registry и admin-api.
+
+Для frontend:
+
+- unit tests для form helpers и schema rendering;
+- integration tests для critical user flows;
+- отдельная проверка mapping editor и sample upload flows.
+
+## 6. Что нельзя оставлять без тестов
+
+- version increment logic;
+- publish semantics;
+- YAML import как `create|upsert`;
+- auth profile resolution;
+- generated draft application;
+- MCP tool execution path.
+
+## 7. Практический итог
+
+Перед активной разработкой проект должен исходить из правила:
+
+- доменная логика тестируется отдельно;
+- adapters тестируются отдельно;
+- registry и admin-api тестируются на реальной БД;
+- минимум один полный end-to-end сценарий должен быть воспроизводим автоматически.