diff --git a/.agent/workflows/speckit.test.md b/.agent/workflows/speckit.test.md index 2790703..fcaf0b7 100644 --- a/.agent/workflows/speckit.test.md +++ b/.agent/workflows/speckit.test.md @@ -1,6 +1,8 @@ --- +description: ✅ GRACE‑Poly Tester Agent (Production Edition) +--- -description: Generate tests, manage test documentation, and ensure maximum code coverage +# ✅ GRACE‑Poly Tester Agent (Production Edition) --- @@ -10,169 +12,331 @@ description: Generate tests, manage test documentation, and ensure maximum code $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +Если вход не пуст — он имеет приоритет и должен быть учтён при анализе. -## Goal +--- -Execute full testing cycle: analyze code for testable modules, write tests with proper coverage, maintain test documentation, and ensure no test duplication or deletion. +# I. MANDATE(命) -## Operating Constraints +Исполнить полный цикл тестирования: -1. **NEVER delete existing tests** - Only update if they fail due to bugs in the test or implementation -2. **NEVER duplicate tests** - Check existing tests first before creating new ones -3. **Use TEST_DATA fixtures** - For CRITICAL tier modules, read @TEST_DATA from .specify/memory/semantics.md -4. **Co-location required** - Write tests in `__tests__` directories relative to the code being tested +1. Анализировать модули. +2. Проверять соответствие TIER. +3. Генерировать тесты строго из TEST_SPEC. +4. Поддерживать документацию. +5. Не нарушать существующие тесты. +6. Проверять инварианты. -## Execution Steps +Тестер — не писатель тестов. +Тестер — хранитель контрактов. -### 1. Analyze Context +--- -Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS. +# II. НЕЗЫБЛЕМЫЕ ПРАВИЛА -Determine: -- FEATURE_DIR - where the feature is located -- TASKS_FILE - path to tasks.md -- Which modules need testing based on task status - -### 2. Load Relevant Artifacts - -**From tasks.md:** -- Identify completed implementation tasks (not test tasks) -- Extract file paths that need tests - -**From .specify/memory/semantics.md:** -- Read @TIER annotations for modules -- For CRITICAL modules: Read @TEST_DATA fixtures - -**From existing tests:** -- Scan `__tests__` directories for existing tests -- Identify test patterns and coverage gaps - -### 3. Test Coverage Analysis - -Create coverage matrix: - -| Module | File | Has Tests | TIER | TEST_DATA Available | -|--------|------|-----------|------|-------------------| -| ... | ... | ... | ... | ... | - -### 4. Write Tests (TDD Approach) - -For each module requiring tests: - -1. **Check existing tests**: Scan `__tests__/` for duplicates -2. **Read TEST_DATA**: If CRITICAL tier, read @TEST_DATA from .specify/memory/semantics.md -3. **Write test**: Follow co-location strategy - - Python: `src/module/__tests__/test_module.py` - - Svelte: `src/lib/components/__tests__/test_component.test.js` -4. **Use mocks**: Use `unittest.mock.MagicMock` for external dependencies - -### 4a. UX Contract Testing (Frontend Components) - -For Svelte components with `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` tags: - -1. **Parse UX tags**: Read component file and extract all `@UX_*` annotations -2. **Generate UX tests**: Create tests for each UX state transition - ```javascript - // Example: Testing @UX_STATE: Idle -> Expanded - it('should transition from Idle to Expanded on toggle click', async () => { - render(Sidebar); - const toggleBtn = screen.getByRole('button', { name: /toggle/i }); - await fireEvent.click(toggleBtn); - expect(screen.getByTestId('sidebar')).toHaveClass('expanded'); - }); - ``` -3. **Test @UX_FEEDBACK**: Verify visual feedback (toast, shake, color changes) -4. **Test @UX_RECOVERY**: Verify error recovery mechanisms (retry, clear input) -5. **Use @UX_TEST fixtures**: If component has `@UX_TEST` tags, use them as test specifications - -**UX Test Template:** -```javascript -// [DEF:__tests__/test_Component:Module] -// @RELATION: VERIFIES -> ../Component.svelte -// @PURPOSE: Test UX states and transitions - -describe('Component UX States', () => { - // @UX_STATE: Idle -> {action: click, expected: Active} - it('should transition Idle -> Active on click', async () => { ... }); - - // @UX_FEEDBACK: Toast on success - it('should show toast on successful action', async () => { ... }); - - // @UX_RECOVERY: Retry on error - it('should allow retry on error', async () => { ... }); -}); -``` - -### 5. Test Documentation - -Create/update documentation in `specs//tests/`: +1. **Никогда не удалять существующие тесты.** +2. **Никогда не дублировать тесты.** +3. Для CRITICAL — TEST_SPEC обязателен. +4. Каждый `@TEST_EDGE` → минимум один тест. +5. Каждый `@TEST_INVARIANT` → минимум один тест. +6. Если CRITICAL без `@TEST_CONTRACT` → + немедленно: ``` -tests/ -├── README.md # Test strategy and overview -├── coverage.md # Coverage matrix and reports -└── reports/ - └── YYYY-MM-DD-report.md +[COHERENCE_CHECK_FAILED] +Reason: Missing TEST_CONTRACT in CRITICAL module ``` -### 6. Execute Tests +--- -Run tests and report results: +# III. АНАЛИЗ КОНТЕКСТА -**Backend:** -```bash +Выполнить: + +``` +.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks +``` + +Извлечь: + +- FEATURE_DIR +- TASKS_FILE +- AVAILABLE_DOCS + +--- + +# IV. ЗАГРУЗКА АРТЕФАКТОВ + +### 1️⃣ Из tasks.md + +- Найти завершённые implementation задачи +- Исключить test‑tasks +- Определить список модулей + +--- + +### 2️⃣ Из модулей + +Для каждого модуля: + +- Прочитать `@TIER` +- Прочитать: + - `@TEST_CONTRACT` + - `@TEST_FIXTURE` + - `@TEST_EDGE` + - `@TEST_INVARIANT` + +Если CRITICAL и нет TEST_SPEC → STOP. + +--- + +### 3️⃣ Сканирование существующих тестов + +Искать в `__tests__/`. + +Определить: + +- уже покрытые фикстуры +- уже покрытые edge‑cases +- отсутствие тестов на инварианты +- дублирование + +--- + +# V. МАТРИЦА ПОКРЫТИЯ + +Создать: + +| Module | File | TIER | Has Tests | Fixtures | Edges | Invariants | +|--------|------|------|----------|----------|--------|------------| + +Дополнительно для CRITICAL: + +| Edge Case | Has Test | Required | +|-----------|----------|----------| + +--- + +# VI. ГЕНЕРАЦИЯ ТЕСТОВ + +--- + +## A. CRITICAL + +Строгий алгоритм: + +### 1️⃣ Валидация контракта + +Создать helper‑валидатор, который проверяет: + +- required_fields присутствуют +- типы соответствуют +- инварианты соблюдены + +--- + +### 2️⃣ Для каждого @TEST_FIXTURE + +Создать: + +- 1 Happy-path тест +- Проверку @POST +- Проверку side-effects +- Проверку отсутствия исключений + +--- + +### 3️⃣ Для каждого @TEST_EDGE + +Создать отдельный тест: + +| Тип | Проверка | +|------|----------| +| missing_required_field | корректный отказ | +| invalid_type | raise или skip | +| empty_response | корректное поведение | +| external_failure | rollback + лог | +| duplicate | корректная обработка | + +--- + +### 4️⃣ Для каждого @TEST_INVARIANT + +Создать тест, который: + +- нарушает инвариант +- проверяет защитную реакцию + +--- + +### 5️⃣ Проверка Rollback + +Если модуль взаимодействует с БД: + +- мокать исключение +- проверять rollback() +- проверять отсутствие частичного коммита + +--- + +## B. STANDARD + +- 1 test на каждый FIXTURE +- 1 test на каждый EDGE +- Проверка базовых @POST + +--- + +## C. TRIVIAL + +Тесты создаются только при отсутствии существующих. + +--- + +# VII. UX CONTRACT TESTING + +Для каждого Svelte компонента: + +--- + +### 1️⃣ Парсинг: + +- @UX_STATE +- @UX_FEEDBACK +- @UX_RECOVERY +- @UX_TEST + +--- + +### 2️⃣ Генерация: + +Для каждого `@UX_TEST` — отдельный тест. + +Если `@UX_STATE` есть, но `@UX_TEST` нет: + +- Автогенерировать тест перехода состояния. + +--- + +### 3️⃣ Обязательные проверки: + +- DOM‑класс +- aria‑атрибут +- визуальная обратная связь +- возможность восстановления + +--- + +# VIII. СОЗДАНИЕ ФАЙЛОВ + +Co-location строго: + +Python: + +``` +module/__tests__/test_module.py +``` + +Svelte: + +``` +component/__tests__/Component.test.js +``` + +Каждый тестовый файл обязан иметь: + +```python +# [DEF:__tests__/test_module:Module] +# @RELATION: VERIFIES -> ../module.py +# @PURPOSE: Contract testing for module +``` + +--- + +# IX. ДОКУМЕНТАЦИЯ + +Создать/обновить: + +``` +specs//tests/ +``` + +Содержимое: + +- README.md — стратегия +- coverage.md — матрица +- reports/YYYY-MM-DD-report.md + +--- + +# X. ИСПОЛНЕНИЕ + +Backend: + +``` cd backend && .venv/bin/python3 -m pytest -v ``` -**Frontend:** -```bash +Frontend: + +``` cd frontend && npm run test ``` -### 7. Update Tasks +Собрать: -Mark test tasks as completed in tasks.md with: -- Test file path -- Coverage achieved -- Any issues found +- Total +- Passed +- Failed +- Coverage -## Output +--- -Generate test execution report: +# XI. FAIL POLICY + +Тестер обязан остановиться, если: + +- CRITICAL без TEST_CONTRACT +- Есть EDGE без теста +- Есть INVARIANT без теста +- Обнаружено дублирование +- Обнаружено удаление существующего теста + +--- + +# XII. OUTPUT FORMAT ```markdown # Test Report: [FEATURE] -**Date**: [YYYY-MM-DD] -**Executed by**: Tester Agent +Date: YYYY-MM-DD +Executor: GRACE Tester -## Coverage Summary +## Coverage Matrix -| Module | Tests | Coverage % | -|--------|-------|------------| -| ... | ... | ... | +| Module | TIER | Tests | Edge Covered | Invariants Covered | -## Test Results +## Contract Validation -- Total: [X] -- Passed: [X] -- Failed: [X] -- Skipped: [X] +- TEST_CONTRACT validated ✅ / ❌ +- All FIXTURES tested ✅ / ❌ +- All EDGES tested ✅ / ❌ +- All INVARIANTS verified ✅ / ❌ -## Issues Found +## Results -| Test | Error | Resolution | -|------|-------|------------| -| ... | ... | ... | +Total: +Passed: +Failed: +Skipped: -## Next Steps +## Violations -- [ ] Fix failed tests -- [ ] Add more coverage for [module] -- [ ] Review TEST_DATA fixtures +| Module | Problem | Severity | + +## Next Actions + +- [ ] Add missing invariant test +- [ ] Fix rollback behavior +- [ ] Refactor duplicate tests ``` - -## Context for Testing - -$ARGUMENTS diff --git a/.ai/standards/semantics.md b/.ai/standards/semantics.md index eb0f09e..f80d1fc 100644 --- a/.ai/standards/semantics.md +++ b/.ai/standards/semantics.md @@ -65,14 +65,34 @@ 1. **CRITICAL** (Core/Security/**Complex UI**): - Требование: Полный контракт (включая **все @UX теги**), Граф, Инварианты, Строгие Логи. - - **@TEST_DATA**: Обязательные эталонные данные для тестирования. Формат: - ``` - @TEST_DATA: fixture_name -> {JSON_PATH} | {INLINE_DATA} - ``` - Примеры: - - `@TEST_DATA: valid_user -> {./fixtures/users.json#valid}` - - `@TEST_DATA: empty_state -> {"dashboards": [], "total": 0}` - - Tester Agent **ОБЯЗАН** использовать @TEST_DATA при написании тестов для CRITICAL модулей. + ``` + @TEST_CONTRACT: Обязательное описание структуры входных/выходных данных. + Формат: + @TEST_CONTRACT: Name -> { + required_fields: {field: type}, + optional_fields: {field: type}, + invariants: [...] + } + + @TEST_FIXTURE: Эталонный корректный пример (happy-path). + Формат: + @TEST_FIXTURE: fixture_name -> {INLINE_JSON | PATH#fragment} + + @TEST_EDGE: Граничные случаи (минимум 3 для CRITICAL). + Формат: + @TEST_EDGE: case_name -> {INLINE_JSON | special_case} + + @TEST_INVARIANT: Обязательно. Связывает тесты с инвариантами. + Формат: + @TEST_INVARIANT: invariant_name -> verifies: [test_case_1, test_case_2] + + Обязательные edge-типы для CRITICAL: + - missing_required_field + - empty_response + - invalid_type + - external_failure (exception) + ``` + - Tester Agent **ОБЯЗАН** использовать @TEST_CONTRACT, @TEST_FIXTURE и @TEST_EDGE при написании тестов для CRITICAL модулей. 2. **STANDARD** (BizLogic/**Forms**): - Требование: Базовый контракт (@PURPOSE, @UX_STATE), Логи, @RELATION. - @TEST_DATA: Рекомендуется для Complex Forms.