diff --git a/AGENTS.md b/AGENTS.md index e6653e8..b785fb7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -354,6 +354,87 @@ response.set_cookie( - Tables auto-created on startup - Use `init_db()` and `close_db()` in lifespan +## TDD Development Workflow + +This project uses **Test-Driven Development (TDD)** with a formal test agreement process. + +### Feature Lifecycle + +``` +User: "начнем новую фичу" + | + v +Discovery Phase (автоматически) + |-- Анализ существующего кода + |-- Определение затронутых слоев DDD + |-- Рекомендации по тесткейсам + | + v +User Agreement (согласование) + |-- Пользователь подтверждает/корректирует тесткейсы + | + v +Test Design + |-- Актуализация FEATURE_*.md + |-- Создание artifact: pyaqa/feature/{feature-name}.md + |-- Назначение TC-UNIT-NNN, TC-API-NNN, TC-WEB-NNN, TC-E2E-NNN + | + v +Write Tests (RED) + |-- Написать тесты, убедиться что они падают + | + v +Implementation (GREEN) + |-- Domain -> Application -> Infrastructure -> Presentation + |-- Минимальная реализация для прохождения тестов + | + v +Refactor + |-- Улучшение кода с сохранением зеленых тестов + |-- Линтеры, type checker + | + v +Verification + |-- ruff check, ruff format, isort, mypy + |-- pytest (coverage ≥70%) + |-- E2E tests + | + v +User Acceptance + |-- Пользователь подтверждает приемку + | + v +Commit (во все затронутые проекты) + |-- blog, pytfm, pyaqa (root) +``` + +### Branch Naming +- Формат: `feature/{feature-name}` +- База: `dev` + +### Test Case IDs +- `TC-UNIT-NNN` — unit тесты (domain, use cases) +- `TC-API-NNN` — API endpoint тесты +- `TC-WEB-NNN` — Web route тесты (HTML responses) +- `TC-E2E-NNN` — End-to-end тесты (Playwright) + +### Test Level Selection +Все 4 уровня по умолчанию. Можно сокращать в зависимости от фичи: +- **Domain-only фича**: только TC-UNIT +- **API-only фича**: TC-UNIT + TC-API +- **Web UI фича**: TC-UNIT + TC-WEB + TC-E2E +- **Full-stack фича**: все 4 уровня + +### Artifact Location +- **Шаблон**: `pyaqa/feature/TEMPLATE.md` +- **Артефакт фичи**: `pyaqa/feature/{feature-name}.md` + +### Commit Rules +При приемке фичи коммитить во ВСЕ затронутые подпроекты: +1. `blog/` — если затронут +2. `pytfm/` — если затронут +3. `pyaqa/` (root) — всегда (обновление ссылок на подпроекты) + ## Notes - Web routes (`app/presentation/web/routes.py`) currently use `MockPost` and `MOCK_POSTS` instead of real use cases — integrate with actual use cases when ready diff --git a/tests/AGENTS.md b/tests/AGENTS.md index 3544366..bf415ea 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -61,12 +61,66 @@ Agents MUST consult these files before adding or modifying tests. - **Mock pattern**: `Mock(spec=Interface)` or `MagicMock(spec=Interface)` — project uses both inconsistently - **Async mocking**: Use `AsyncMock()` for async methods (commit, rollback, repo methods) +## TDD Test Case Workflow + +### Adding a Feature Test + +1. **User triggers**: `"начнем новую фичу"` +2. **Agent analyzes**: существующий код, затронутые слои, рекомендует тесткейсы +3. **User agrees**: подтверждает или корректирует набор тесткейсов +4. **Agent creates**: + - `pyaqa/feature/{feature-name}.md` — артефакт фичи + - Обновляет `FEATURE_*.md` — добавляет новые TC +5. **Agent writes tests**: в порядке TC-UNIT → TC-API → TC-WEB → TC-E2E +6. **Agent marks**: в артефакте статус "tests-ready" +7. **Agent implements**: фичу по слоям (Domain → Application → Infra → Presentation) +8. **Agent verifies**: линтеры, тесты, coverage +9. **User accepts**: подтверждает приемку +10. **Agent commits**: во все затронутые проекты + +### Test Case Assignment Rules + +- **TC-UNIT-NNN**: unit тесты (domain, use cases) +- **TC-API-NNN**: API endpoint тесты +- **TC-WEB-NNN**: Web route тесты (HTML responses, redirects) +- **TC-E2E-NNN**: End-to-end тесты (Playwright) + +Нумерация внутри каждого уровня последовательная. Пропуски допустимы только при удалении устаревших тестов. + +### Test Case Format + +```markdown +### TC-UNIT-NNN: Test Name +- **Type:** Positive | Negative | Policy +- **Layer:** Unit | API | Web | E2E +- **File:** `path/to/test.py::TestClass::test_method` +- **Expected:** Что ожидается +- **Last Verified:** YYYY-MM-DD +``` + +### Red → Green → Refactor + +- **RED**: Написать тест, убедиться что он падает +- **GREEN**: Написать минимальную реализацию, тест проходит +- **REFACTOR**: Улучшить код, тесты остаются зелеными + +### Test Coverage Requirements + +| Layer | Minimum Coverage | Notes | +|-------|-----------------|-------| +| Unit | 80% | Domain + Application | +| API | 70% | Endpoints + deps | +| Web | 60% | Routes + handlers | +| E2E | Cover all AC | Все acceptance criteria | + ## Anti-Patterns - Do NOT add `@pytest.mark.asyncio` to `async def` tests (auto mode handles it) - Do NOT use bare `Mock()` without `spec=` for interface mocks - Do NOT delete tests to "fix" coverage — this is grounds for rollback - Do NOT put fixtures in `__init__.py` — use `conftest.py` +- Do NOT write implementation before tests (no TDD bypass) +- Do NOT skip RED phase (tests must fail before implementation) ## Notes