docs: добавлен TDD workflow в AGENTS.md и tests/AGENTS.md
- blog/AGENTS.md: раздел TDD Development Workflow с lifecycle фичи - tests/AGENTS.md: правила TDD для тестов (RED/GREEN/REFACTOR, TC-ID формат) - Описаны уровни тесткейсов: TC-UNIT, TC-API, TC-WEB, TC-E2E - Добавлены правила коммита во все подпроекты
This commit is contained in:
81
AGENTS.md
81
AGENTS.md
@@ -354,6 +354,87 @@ response.set_cookie(
|
|||||||
- Tables auto-created on startup
|
- Tables auto-created on startup
|
||||||
- Use `init_db()` and `close_db()` in lifespan
|
- 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
|
## 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
|
- 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
|
||||||
|
|||||||
@@ -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
|
- **Mock pattern**: `Mock(spec=Interface)` or `MagicMock(spec=Interface)` — project uses both inconsistently
|
||||||
- **Async mocking**: Use `AsyncMock()` for async methods (commit, rollback, repo methods)
|
- **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
|
## Anti-Patterns
|
||||||
|
|
||||||
- Do NOT add `@pytest.mark.asyncio` to `async def` tests (auto mode handles it)
|
- 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 use bare `Mock()` without `spec=` for interface mocks
|
||||||
- Do NOT delete tests to "fix" coverage — this is grounds for rollback
|
- Do NOT delete tests to "fix" coverage — this is grounds for rollback
|
||||||
- Do NOT put fixtures in `__init__.py` — use `conftest.py`
|
- 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
|
## Notes
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user