crank/docs/testing-strategy.md

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

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

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

Цель:

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

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

2.1. Unit tests

Покрывают:

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

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

• валидацию схем;
• JSONPath parsing;
• применение input/output mapping;
• генерацию чернового mapping;

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

Отдельно для Community-протокола:

• REST adapter;

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

• сборку request;
• нормализацию response;
• обработку ошибок;
• стабильность mapping context.

2.4. End-to-end tests

Минимально нужны сценарии:

• создать REST operation -> протестировать -> опубликовать -> вызвать как MCP tool;

3. Что должно быть покрыто обязательно

Обязательно с первого этапа

• schema validation;
• mapping execution;
• YAML import/export roundtrip;
• versioning logic registry;
• publish flow.

Обязательно до первого демо

• хотя бы один end-to-end сценарий для REST;
• negative tests на invalid JSONPath;

4. Формат тестовых данных

Рекомендуется использовать:

• JSON fixtures для sample input/output;
• YAML golden files для export/import;
• 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 сценарий должен быть воспроизводим автоматически.