Test manuali strutturati: checklist riproducibili

Test automatici sono potenti ma non sostituiscono test manuali. Un occhio umano coglie cose che gli automatici saltano: estetica, fluidità, accessibilità reale, sensazione di velocità. Ma test manuali “a vista” sono inaffidabili: dipendono da cosa ricordi di provare. Checklist strutturate sono la versione ripetibile dei test manuali.

Perché questa lezione conta

Senza checklist, ogni test manuale è “io provo qualche cosa”. Quel “qualche cosa” varia di volta in volta. Risultato: cose che funzionavano si rompono senza che te ne accorga; cose nuove non vengono testate sotto certi browser/casi. Checklist riproducibile = test manuale che chiunque può eseguire, ottenendo gli stessi segnali. Trasforma test in pratica condivisibile.

Obiettivo operativo

Alla fine devi saper:

1. costruire checklist per un flusso utente in formato riproducibile;
2. eseguire la checklist registrando evidenze (screenshot, dati, output);
3. usare AI per generare checklist iniziale e poi affinarla con esperienza.

Nucleo della lezione

1. Struttura di una checklist

Ogni voce di checklist ha 5 elementi:

Setup: stato di partenza richiesto. “Utente loggato come admin”, “DB con 3 task di esempio”, “Browser pulito senza cache”.

Azione: cosa fai. “Click su Salva”, “Apri /admin/users”, “Tab attraverso form”.

Dato usato: input concreto. “Email: test@example.com”, “Password: minlength6”, “File: 2MB jpg”.

Risultato atteso: cosa dovrebbe succedere. “Modal conferma con messaggio X”, “Redirect a /home con welcome”, “Bordo rosso e errore inline”.

Risultato osservato: cosa succede. Compili durante esecuzione, non a memoria.

Esempio voce:

[ ] Login con credenziali valide
    Setup: utente `test@test.it` esiste, password "test1234". Browser pulito.
    Azione: apri /login, compila email e password, click "Accedi".
    Dato: email = `test@test.it`, password = test1234
    Atteso: redirect a /home con saluto "Benvenuto, Test"
    Osservato: ___

Compilato durante test → tracciabile, ripetibile.

2. Cosa testare

Categorie da coprire per app web:

Flussi utente principali:

• registrazione + login
• recupero password
• onboarding
• creazione/modifica/cancellazione di entità chiave
• pagamento (se applicabile)
• logout

Stati UI:

• vuoto (no dati)
• loading (durante fetch)
• errore (rete, server, validazione)
• successo (conferma esplicita)
• pieno (lista lunga, scroll)

Browser e dispositivi:

• browser principali (Chrome, Safari, Firefox)
• mobile vs desktop (viewport diverse)
• iOS Safari (peculiarità: vh, scroll, touch)
• altre lingue se app supporta i18n

Accessibilità:

• navigazione solo da tastiera (Tab, Shift+Tab, Enter, Esc)
• focus visibile su elementi interattivi
• contrasto colori
• screen reader (almeno VoiceOver/NVDA su una pagina chiave)

Performance percepita:

• caricamento iniziale
• transizioni
• form submit
• ricerca

Resilience:

• refresh durante operazione
• back/forward del browser
• doppio tab della stessa app
• offline → online

Per ogni feature, scegli categorie pertinenti e voci specifiche.

3. Registrazione evidenze

Test manuale senza traccia = test che non c’è stato. Registra:

• Screenshot: dei punti critici. Tools: Cmd+Shift+4 macOS, Snip&Sketch Windows, screenshot integrati nel browser.
• Console log: copia errori/warning rilevanti, verbatim.
• Network: status code di chiamate API, payload se rilevante.
• Dati usati: email, password, valori specifici → riproducibilità.
• Versione/commit testato: hash git breve. Quando aggiungi commit, ripeti checklist.
• Data/ora del test.

Salva tutto in cartella qa/ o sezione del task tracker. Diventa archivio di test sessions.

Caso guidato: da prova casuale a checklist

Prova casuale:

Ho provato il form e sembra ok.

Questa frase non è riutilizzabile. Non dice browser, dati, stato iniziale, risultato atteso, né cosa è stato escluso. Trasformala:

## Feature: creazione task
Versione: commit `abc123`
Browser: Chrome desktop, viewport 1440x900

Setup:
- utente già loggato;
- lista task vuota;
- DevTools Console aperta.

[ ] Creazione con titolo valido
Dato: "Pagare bolletta"
Atteso: nuova riga in lista, messaggio "Task creato", input svuotato.
Osservato:

[ ] Titolo vuoto
Dato: campo vuoto
Atteso: submit bloccato, messaggio "Inserisci un titolo".
Osservato:

[ ] Doppio click su Salva
Dato: "Comprare pane"
Atteso: un solo task creato.
Osservato:

[ ] Refresh dopo creazione
Atteso: task ancora presente.
Osservato:

La checklist non deve coprire tutto il mondo. Deve rendere ripetibile ciò che hai davvero provato. Quando trovi un bug, aggiungi una voce: quel bug diventa regressione futura.

Procedura pratica

Per nuova feature significativa:

1. Genera checklist iniziale (con AI se serve, vedi prompt sotto).
2. Personalizza: aggiungi voci specifiche al tuo caso, rimuovi non pertinenti.
3. Esegui: in ordine, una voce alla volta. Compili “osservato” man mano.
4. Annota difetti: bug trovati con screenshot/log.
5. Salva: checklist + evidenze in cartella dedicata.
6. Aggiorna checklist: voci che hanno trovato bug → aggiungi a checklist permanente per regression future.

Laboratorio guidato

Feature: form di iscrizione newsletter.

Checklist iniziale:

SETUP COMUNE
- Browser pulito (no cookie precedenti)
- /newsletter accessibile

[ ] 1. Iscrizione con email valida
    Azione: inserisci "test@example.com", click "Iscrivi"
    Atteso: messaggio "Iscritto! Ti abbiamo inviato email di conferma"
    Osservato: ___

[ ] 2. Email vuota
    Azione: clicca "Iscrivi" senza compilare
    Atteso: bordo rosso campo email + errore "Inserisci email"
    Osservato: ___

[ ] 3. Email malformata
    Azione: inserisci "abc", click "Iscrivi"
    Atteso: errore "Email non valida"
    Osservato: ___

[ ] 4. Email già iscritta
    Azione: inserisci email già nel sistema, click "Iscrivi"
    Atteso: messaggio "Email già iscritta. Vuoi riinviare conferma?"
    Osservato: ___

[ ] 5. Tastiera-only
    Azione: senza mouse, Tab, Tab, type email, Tab, Enter
    Atteso: form si compila, submit, conferma
    Osservato: ___

[ ] 6. Mobile (Safari iOS, viewport 375)
    Azione: form aperto, compila, submit
    Atteso: layout responsive, tastiera adatta (email keyboard)
    Osservato: ___

[ ] 7. Offline durante submit
    Azione: chrome devtools → offline, compila form, submit
    Atteso: messaggio "Connessione assente. Riprova"
    Osservato: ___

[ ] 8. Refresh dopo submit successo
    Azione: dopo conferma, F5
    Atteso: pagina ricarica, form vuoto, no doppio invio
    Osservato: ___

[ ] 9. Back browser dopo submit
    Azione: dopo conferma, click freccia indietro
    Atteso: pagina precedente, no resubmit confirmation
    Osservato: ___

[ ] 10. Submit ripetuto rapidamente (doppio click)
    Azione: click rapidi consecutivi
    Atteso: solo un invio (debounce/disable)
    Osservato: ___

10 voci, 30-45 min di esecuzione. Trovi bug = correggi + aggiungi voce per regression.

Output atteso

Una checklist per la prossima feature significativa, in formato testuale o markdown, con sezioni setup + voci + spazio “osservato”. Salvabile in cartella qa/feature-name.md.

Quando fermare il test

Una checklist non è un romanzo infinito. Per una feature media, 10-15 voci bastano. Fermati quando hai coperto: flusso principale, un errore prevedibile, un caso limite, refresh o ritorno pagina, mobile o tastiera. Se una voce richiede più di 5 minuti, probabilmente è troppo grande: dividila.

Quando trovi un bug, non continuare come se niente fosse. Segna la voce come fallita, raccogli evidenza minima e apri un sotto-task. Dopo il fix, ripeti quella voce e almeno due voci vicine. Questo è il passaggio che trasforma test manuale in protezione da regressioni.

Per una consegna didattica, aggiungi sempre una riga finale: “decisione”. Può essere passa, passa con note, blocca. Così lo studente impara che testare non è solo osservare: è decidere se il lavoro può avanzare.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: trasformare prove casuali in verifiche ripetibili e condivisibili. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Checklist per flussi utente: setup, azione, dato usato, risultato atteso, risultato osservato.
• Test su browser, viewport, stato vuoto, stato carico, errore, refresh, navigazione da tastiera.
• Registrare prove: screenshot, log console, dati usati, commit o versione testata.

3. Applicazione: svolgi il laboratorio: scrivere ed eseguire una checklist manuale per una pagina o un flusso di autenticazione simulato. L’output da ottenere è: una checklist riproducibile che un’altra persona potrebbe eseguire ottenendo gli stessi segnali.

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

• ho almeno una checklist scritta per il mio progetto principale;
• ogni voce ha setup + azione + dato + atteso;
• registro screenshot/log durante esecuzione;
• aggiungo voci alla checklist quando un bug emerge;
• conosco le 6 categorie di test (flussi, stati, browser, accessibilità, performance, resilience).

Errori comuni

“Provo a vista”. Senza checklist, manchi cose. Sempre.

Voci vaghe. “Verifica funzionamento”. Non testabile. Cosa? Come? Con quale dato?

Nessuna registrazione. Test fatto, niente traccia. Domani ripeti tutto.

Mai aggiornare. Bug trovato → fix → checklist immutata. Bug torna fra mesi.

Solo happy path. 80% delle voci sono caso normale. Edge case e ostili sottorappresentati.

Test solo su browser principale. Mobile/Safari iOS hanno pattern specifici. Almeno uno sguardo lì.

Niente accessibilità. Tastiera-only è 5 minuti, screen reader 10. Skipparli = utenti reali esclusi.

Prompt di lavoro

Genera checklist di test manuali per questa feature: [descrizione]

Categorie da coprire (scegli pertinenti):
- flussi principali (3-5 voci)
- stati UI (vuoto, loading, errore, successo, pieno) (1 voce per stato)
- browser/dispositivi (Chrome, Safari, mobile)
- accessibilità tastiera (1-2 voci)
- resilience (refresh, back, offline) (2-3 voci)

Output: lista numerata con per ogni voce:
- setup
- azione
- dato concreto
- atteso

Spazio per "osservato" → vuoto, da compilare.

Lunghezza target: 10-15 voci per feature media.

Niente test automatici. Niente codice. Solo checklist eseguibile da umano.

Esercizio finale

Esegui checklist per una feature del tuo progetto in produzione. Probabilmente trovi 1-3 bug minori che usavi senza notare. Quei bug sono lo stato di base senza checklist: presenti ma invisibili. Per ognuno: fix, aggiungi voce permanente alla checklist, regressi prevenuti per il futuro.