test semantic harden

2026-02-26 18:26:11 +03:00
parent 4ff6d307f8
commit 484019e750
2 changed files with 323 additions and 139 deletions
--- 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/<feature>/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/<feature>/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
--- 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.