Capstone — lettura, test, debug del proprio prototipo

Codice generato non è codice tuo finché non lo capisci. Lettura strutturata + test + debug del prototipo trasforma “ho fatto generare l’app” in “ho costruito l’app”. Il salto è nell’analisi consapevole, non nella tastiera.

Perché questa lezione conta

Senza lettura attenta, il codice generato ti scivola fra le mani. Aggiungi feature, qualcosa si rompe, non sai dove. Test scopre regressioni. Debug forza comprensione. Le tre attività insieme convertono codice ricevuto in codice posseduto.

Obiettivo operativo

Alla fine della sessione devi avere:

1. mappa file del capstone (entry point, flussi, dati);
2. tracciamento di un dato critico (input → output);
3. test minimi automatici + checklist manuale;
4. un bug fixato seguendo il ciclo regression.

Nucleo della lezione

1. Mappa del capstone

Applica lezione 41 al tuo capstone:

• punto d’ingresso (es. src/pages/index.astro);
• componenti principali e loro scopo;
• moduli logica (src/lib/);
• dipendenze esterne;
• struttura file pulita;
• comandi disponibili.

Per ogni componente principale: scrivi 1 riga “fa X”. Se non riesci, è segnale di poca comprensione → lettura più approfondita.

Salva mappa in docs/orientamento.md. Documento auto-aggiornabile.

2. Flusso dati principale

Applica lezione 42:

• prendi un dato critico (es. “abitudine completata oggi”);
• traccia dall’input (click toggle) all’output (UI mostra ✓);
• attraverso: state component → chiamata toggleEntry() → IndexedDB write → ri-fetch entries → ri-render lista.

Diagramma testuale:

[Click toggle in UI]
   ↓
[onClickToggle handler in HabitList]
   ↓
[toggleEntry(habitId, date) in db.ts]
   ↓
[IndexedDB transaction: read entry → flip done → write]
   ↓
[event "entry.toggled" emitted]
   ↓
[HabitList re-fetches entries]
   ↓
[UI ri-render con nuovo stato]

Punti di rottura potenziali:

• IndexedDB transaction fallisce → cosa vede utente?
• click multiplo veloce → race condition?
• date in formato sbagliato → entry non trovata?
• Service Worker interfere → cache stale?

Per ognuno: c’è gestione? Test?

3. Test e debug

Test manuali strutturati (lezione 49): checklist per flusso principale.

Esempio:

[ ] 1. Aggiungi prima abitudine
    Setup: app vuota
    Azione: click "+", inserisci "Bere acqua", color blu, salva
    Atteso: appare in lista
    
[ ] 2. Toggle done oggi
    Setup: 1 abitudine
    Azione: click checkbox accanto a "Bere acqua"
    Atteso: checkbox spuntata, "✓ oggi" mostrato
    
[ ] 3. Refresh persiste
    Setup: 1 abitudine + checked oggi
    Azione: F5
    Atteso: stato preservato

... ecc

Test automatici minimi (lezione 50):

• unit per formatDate(date): string → 5 test casi limite.
• unit per toggleEntry(habitId, date): crea, toggle, verifica.
• smoke: build + serve + curl localhost.

Aggiungi questi prima di chiudere capstone.

Debug di un bug: trova un bug reale nel tuo capstone (probabilmente esiste). Esempi tipici:

• toggle non persiste dopo refresh in alcune condizioni;
• empty state mostra layout rotto;
• mobile: bottom navigation copre contenuto.

Per il bug:

1. riproduci minimamente (lezione 48);
2. bug report 6 sezioni;
3. diagnosi con AI (ipotesi multiple, no fix subito);
4. fix mirato;
5. test di regressione (lezione 52);
6. verifica casi vicini.

Sessione QA guidata

Prima di aggiungere nuove feature al capstone, fai una sessione QA sul prototipo esistente.

Esempio per registro spese:

Versione: commit abc123
Flusso principale: aggiungere spesa e vedere totale mensile.

Checklist:

1. Stato vuoto: apro app senza spese, vedo messaggio utile.
2. Creazione valida: aggiungo 12.50 euro, categoria “cibo”, data oggi.
3. Persistenza: refresh, la spesa resta.
4. Totale: totale mese include la spesa.
5. Input invalido: importo negativo viene rifiutato.
6. Data mancante: errore chiaro.
7. Mobile: form non esce dallo schermo.
8. Console: nessun errore durante creazione.

Bug trovato:

Se inserisco "12,50" con virgola italiana, il totale diventa 12 invece di 12.50.

Report buono:

Sintomo: parsing importo tronca decimali con virgola.
Atteso: accettare virgola o mostrare errore.
Osservato: salva 12.
File probabile: validateExpenseInput / parseAmount.
Verifica regressione: test con "12,50", "12.50", "abc".

Questo è capstone vero: non solo generare, ma leggere comportamento, trovare bug, costruire prova che non torni.

Report minimo da consegnare

Alla fine della sessione QA, produci un report in questo formato:

# QA Capstone

## Versione
Commit: ...
Data: ...
Browser/ambiente: ...

## Flussi verificati
- ...

## Bug trovati
| Bug | Passi | Atteso | Osservato | Stato |
| --- | --- | --- | --- | --- |

## Fix applicati
- ...

## Verifiche di regressione
- ...

## Rischi rimasti
- ...

Non serve un documento lungo. Serve una traccia che dimostri comprensione del prototipo. Se il report contiene solo “tutto ok”, non è QA: è una dichiarazione. Almeno un rischio rimasto deve esistere, anche piccolo. Saperlo nominare è parte della competenza.

Questo report è anche materiale per la retrospettiva finale: ti mostra dove l’AI ha aiutato, dove ha nascosto complessità e quali controlli vuoi rendere automatici nel prossimo progetto.

Una buona QA non cerca solo bug: misura quanto conosci davvero il software che hai generato e quanto puoi fidarti del prossimo cambiamento.

Procedura pratica

90 minuti:

1. Mappa file (15 min): se non l’hai, scrivi.
2. Tracciamento dato (15 min): un flusso critico, diagramma.
3. Checklist manuale (15 min): scrivi 8-12 voci.
4. Esegui checklist (15 min): trovi bug? Correggi seguendo lezione 52.
5. Test automatici minimi (15 min): 3-5 unit + 1 smoke.
6. Aggiorna doc (10 min): orientamento.md, decisions.md se necessario.
7. Pausa: bilancio.

Laboratorio guidato

Sul tuo capstone esegui sequenza completa.

Esempio scoperta tipica:

Bug trovato durante checklist: “Toggle abitudine alle 23:55 → refresh dopo mezzanotte → toggle scompare”. Causa: chiave entry usa new Date().toISOString().split('T')[0] che cambia da una data all’altra. UI mostra entry “di oggi” basato su data corrente, non data di toggle.

Bug è di prodotto: dati corretti in DB, presentation incoerente quando data cambia tra toggle e visualizzazione.

Fix: invece di “entry per oggi”, mostra “entry per [data corrente del client]” con etichetta esplicita. Data passata mostrata in calendario per cronologia.

Test regressione: simula toggle alle 23:55 + refresh alle 00:05 → calendario mostra entry su data corretta.

Pattern: bug edge case (DST, timezone, change of date) emerge solo con test mirati.

Output atteso

• docs/orientamento.md: mappa file aggiornata;
• docs/data-flow-toggle.md: tracciamento dato critico;
• docs/qa-checklist.md: checklist manuale;
• 3-5 test automatici in src/__tests__/;
• 1 bug fixato con test di regressione.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: dimostrare di comprendere il codice generato e di saperlo mettere sotto verifica. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Mappa dei file del capstone, flusso dati principale e punti in cui possono nascere errori.
• Test manuali per happy path, edge case, input ostili, refresh, mobile e stati vuoti.
• Test automatici minimi o smoke test per proteggere il flusso più importante.

3. Applicazione: svolgi il laboratorio: eseguire una sessione di QA sul capstone, correggere un bug e aggiungere almeno una verifica di regressione. L’output da ottenere è: un report di test con bug trovati, fix applicati, rischi rimasti e comandi di verifica.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• so descrivere ogni file principale del capstone;
• ho tracciato almeno un flusso dati critico;
• ho checklist manuale eseguita almeno una volta;
• ho test automatici minimi;
• ho fixato almeno un bug seguendo ciclo regression.

Errori comuni

Saltare lettura. Codice generato → “funziona” → produzione. Bug futuri inspiegabili.

Niente test. Refactor diventa scommessa.

Bug ignorato perché “raro”. Edge case sono dove utenti reali finiscono.

Test post-bug ma niente bug report. Causa profonda non identificata, simili torneranno.

Tracciare dato da memoria. Senza diagramma scritto, perdi pezzi.

Prompt di lavoro

Aiutami con QA del mio capstone.

Repo: [link o struttura].

In ordine, conducimi attraverso:

1. Mappa file: identifica entry point, componenti, moduli, file di config. Output: docs/orientamento.md.

2. Tracciamento dato critico: prendi flusso "[esempio: aggiunta abitudine]" e tracciamela dall'input all'output. Identifica punti di rottura.

3. Checklist manuale: 10-12 voci che coprono caso normale, edge case, mobile, accessibilità.

4. Test automatici minimi: 3-5 unit test per logica core + 1 smoke.

5. Per ogni potenziale bug emerso, suggerisci come riprodurlo e fixarlo (NO fix subito, voglio capire).

Output: file .md per ognuno, eseguibili.

Esercizio finale

Esegui checklist manuale, conta bug trovati. Probabilmente 2-4. Per ognuno, ciclo completo: report → diagnosi → fix → test regressione. A fine sessione, capstone è significativamente più solido. Decision log e architettura aggiornati riflettono.