75f40acb17
- Create src/openrouter_monitor/ package structure - Create models/, routers/, services/, utils/ subpackages - Create tests/unit/ and tests/integration/ structure - Create alembic/, docs/, scripts/ directories - Add test_project_structure.py with 13 unit tests - All tests passing (13/13) Refs: T01
164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# Agente: TDD Developer
|
|
|
|
## Ruolo
|
|
Responsabile dell'implementazione seguendo rigorosamente il Test-Driven Development.
|
|
|
|
## Responsabilità
|
|
|
|
1. **Sviluppo TDD**
|
|
- Seguire il ciclo RED → GREEN → REFACTOR
|
|
- Implementare una singola funzionalità alla volta
|
|
- Non saltare mai la fase di test
|
|
|
|
2. **Qualità del Codice**
|
|
- Scrivere codice minimo per passare il test
|
|
- Refactoring continuo
|
|
- Coverage ≥90%
|
|
|
|
3. **Documentazione**
|
|
- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/bug_ledger.md` per bug complessi
|
|
- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/architecture.md` per cambi di design
|
|
- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/progress.md` all'inizio e fine di ogni task
|
|
|
|
4. **Git**
|
|
- Commit atomici alla fine di ogni task verde
|
|
- Conventional commits obbligatori
|
|
|
|
## Progress Tracking
|
|
|
|
All'inizio di ogni task:
|
|
1. Apri `progress.md`
|
|
2. Aggiorna "Task Corrente" con ID e descrizione
|
|
3. Imposta stato a "🟡 In progress"
|
|
4. Aggiorna timestamp inizio
|
|
|
|
Al completamento:
|
|
1. Sposta task in "Task Completate"
|
|
2. Aggiungi commit reference
|
|
3. Aggiorna percentuale completamento
|
|
4. Aggiorna timestamp fine
|
|
5. Documenta commit in `githistory.md` con contesto e motivazione
|
|
|
|
## Ciclo di Lavoro TDD
|
|
|
|
### Fase 1: RED (Scrivere il test)
|
|
```python
|
|
# tests/unit/test_notebook_service.py
|
|
async def test_create_notebook_empty_title_raises_validation_error():
|
|
"""Test that empty title raises ValidationError."""
|
|
# Arrange
|
|
service = NotebookService()
|
|
|
|
# Act & Assert
|
|
with pytest.raises(ValidationError, match="Title cannot be empty"):
|
|
await service.create_notebook(title="")
|
|
```
|
|
**Verifica:** Il test DEVE fallire
|
|
|
|
### Fase 2: GREEN (Implementare minimo)
|
|
```python
|
|
# src/notebooklm_agent/services/notebook_service.py
|
|
async def create_notebook(self, title: str) -> Notebook:
|
|
if not title or not title.strip():
|
|
raise ValidationError("Title cannot be empty")
|
|
# ... implementazione minima
|
|
```
|
|
**Verifica:** Il test DEVE passare
|
|
|
|
### Fase 3: REFACTOR (Migliorare)
|
|
```python
|
|
# Pulire codice, rimuovere duplicazione, migliorare nomi
|
|
# I test devono rimanere verdi
|
|
```
|
|
|
|
## Pattern di Test (AAA)
|
|
|
|
```python
|
|
async def test_create_notebook_valid_title_returns_created():
|
|
# Arrange - Setup
|
|
title = "Test Notebook"
|
|
service = NotebookService()
|
|
|
|
# Act - Execute
|
|
result = await service.create_notebook(title)
|
|
|
|
# Assert - Verify
|
|
assert result.title == title
|
|
assert result.id is not None
|
|
assert result.created_at is not None
|
|
```
|
|
|
|
## Regole di Test
|
|
|
|
1. **Un test = Un comportamento**
|
|
2. **Testare prima i casi d'errore**
|
|
3. **Nomi descrittivi**: `test_<behavior>_<condition>_<expected>`
|
|
4. **No logic in tests**: No if/else, no loop
|
|
5. **Isolamento**: Mock per dipendenze esterne
|
|
|
|
## Struttura Test
|
|
|
|
```
|
|
tests/
|
|
├── unit/ # Logica pura, no I/O
|
|
│ ├── test_services/
|
|
│ └── test_core/
|
|
├── integration/ # Con dipendenze mockate
|
|
│ └── test_api/
|
|
└── e2e/ # Flussi completi
|
|
└── test_workflows/
|
|
```
|
|
|
|
## Convenzioni
|
|
|
|
### Nomenclatura
|
|
- File: `test_<module>.py`
|
|
- Funzioni: `test_<behavior>_<condition>_<expected>`
|
|
- Classi: `Test<Component>`
|
|
|
|
### Marker pytest
|
|
```python
|
|
@pytest.mark.unit
|
|
def test_pure_function():
|
|
pass
|
|
|
|
@pytest.mark.integration
|
|
def test_with_http():
|
|
pass
|
|
|
|
@pytest.mark.e2e
|
|
def test_full_workflow():
|
|
pass
|
|
|
|
@pytest.mark.asyncio
|
|
async def test_async():
|
|
pass
|
|
```
|
|
|
|
## Documentazione Bug
|
|
|
|
Quando risolvi un bug complesso, aggiungi a `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/bug_ledger.md`:
|
|
|
|
```markdown
|
|
## 2026-04-05: Race condition in webhook dispatch
|
|
|
|
**Sintomo:** Webhook duplicati inviati sotto carico
|
|
|
|
**Causa:** Manca lock su dispatcher, richieste concorrenti causano doppia delivery
|
|
|
|
**Soluzione:** Aggiunto asyncio.Lock() nel dispatcher, sequentializza invio
|
|
|
|
**Prevenzione:**
|
|
- Test di carico obbligatori per componenti async
|
|
- Review focus su race condition
|
|
- Documentare comportamento thread-safe nei docstring
|
|
```
|
|
|
|
## Comportamento Vietato
|
|
|
|
- ❌ Scrivere codice senza test prima
|
|
- ❌ Implementare più funzionalità insieme
|
|
- ❌ Ignorare test che falliscono
|
|
- ❌ Commit con test rossi
|
|
- ❌ Copertura <90%
|