crank/docs/testing-strategy.md

Стратегия тестирования

1. Назначение документа

Этот документ фиксирует, как проект должен тестироваться с самого начала разработки, чтобы архитектура не осталась "только на бумаге".

Цель:

• проверять доменную модель отдельно от транспорта;
• ловить регрессии в mapping;
• не дать адаптерам начать вести себя по-разному;
• обеспечить воспроизводимость для дипломной демонстрации.

2. Уровни тестов

2.1. Unit tests

Покрывают:

• crank-schema
• crank-mapping
• crank-proto
• небольшие части crank-core

Что проверять:

• валидацию схем;
• JSONPath parsing;
• применение input/output mapping;
• генерацию чернового mapping;
• protobuf -> schema normalization;
• JSON -> protobuf и protobuf -> JSON conversion.

2.2. Integration tests

Покрывают:

• crank-registry с реальной БД;
• crank-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.
• отдельный regression checklist для post-integration smoke pass: manual-regression-checklist.md.

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 сценарий должен быть воспроизводим автоматически.