# Guida ai Test Obiettivo della guida: - capire che tipi di test esistono nel progetto - capire a cosa servono davvero - sapere come lanciarli senza errori - sapere come leggere i risultati - sapere cosa fare quando qualcosa fallisce ## 0) Perche facciamo i test? Un test è un controllo automatico. In pratica: - tu cambi il codice - lanci i test - i test ti dicono se hai rotto qualcosa Se i test sono verdi, hai una buona probabilita che il progetto sia ancora stabile. Se i test sono rossi, c'e un problema da capire e sistemare. ## 1) Struttura delle cartelle test ```text tests/ ├── unit/ # Test della logica pura (molto veloci) ├── integration/ # Test di moduli che comunicano tra loro ├── component/ # Test dei componenti Vue in isolamento ├── stress/ # Test sotto carico (molti client/azioni) ├── e2e/ # Test end-to-end su browser reale └── README.md # Questa guida ``` ## 2) Tecnologie usate - `Vitest`: per `unit`, `integration`, `component`, `stress` - `Playwright`: per `e2e` Tradotto in modo semplice: - Vitest controlla parti interne del progetto - Playwright controlla il comportamento reale dell'app nel browser ## 3) Prerequisiti (prima di tutto) ### 3.1 Installa dipendenze Dalla root del progetto: ```bash npm install ``` ### 3.2 Installa browser Playwright (solo E2E) ```bash npx playwright install chromium firefox ``` Se non fai questo passo, gli E2E possono fallire subito con errore tipo: - `Executable doesn't exist` ## 4) Comandi principali ```bash npm run test # Vitest in watch mode (resta in ascolto) npm run test:all # Tutta la suite Vitest una volta npm run test:unit # Unit + integration npm run test:component # Solo component test npm run test:stress # Solo stress test npm run test:e2e # Tutti gli E2E Playwright npm run test:e2e:ui # Playwright con interfaccia grafica ``` Ordine consigliato (quando vuoi verificare tutto): 1. `npm run test:all` 2. `npm run test:e2e` ## 5) Cosa testa ogni suite (spiegato semplice) ### 5.1 Unit (`tests/unit`) Cosa sono: - test piccoli e veloci sulla logica del gioco A cosa servono: - trovano subito bug in regole punteggio/set/reset Esempi reali nel progetto: - incremento/decremento punti - cambio palla - vittoria set con regola dei 2 punti di scarto - reset stato Quando falliscono: - quasi sempre c'e un problema nella logica core ### 5.2 Integration (`tests/integration`) Cosa sono: - test su pezzi che lavorano insieme (es. WebSocket + handler) A cosa servono: - verificano che i messaggi si muovano nel modo corretto Esempi reali nel progetto: - registrazione client `display`/`controller` - broadcast stato ai client - validazione input malformati - autorizzazioni (solo controller puo inviare certe azioni) Quando falliscono: - spesso c'e problema nel protocollo messaggi o nei controlli di ruolo ### 5.3 Component (`tests/component`) Cosa sono: - test dei componenti Vue senza browser completo A cosa servono: - controllano rendering e comportamento UI locale Esempi reali nel progetto: - punteggio mostrato correttamente - stato connessione - click bottoni controller - dialog reset/config/cambi Quando falliscono: - spesso hai rotto template, computed, metodi o binding ### 5.4 Stress (`tests/stress`) Cosa sono: - test per simulare carico elevato A cosa servono: - verificano che il sistema regga molti client e molte azioni rapide Esempi reali nel progetto: - tanti client display connessi insieme - burst di azioni consecutive Quando falliscono: - possono emergere problemi di performance o consistenza stato ### 5.5 End-to-End (`tests/e2e`) Cosa sono: - test realistici nel browser A cosa servono: - verificano che Controller e Display funzionino davvero insieme File principali: - `basic-flow.spec.cjs`: flusso base Controller <-> Display - `game-operations.spec.cjs`: reset, config, toggle, cambi - `game-simulation.spec.cjs`: simulazione partita - `full-match.spec.cjs`: scenari partita completi - `accessibility.spec.cjs`: controlli accessibilita con axe - `visual-regression.spec.cjs`: confronto screenshot con baseline Nota importante: - gli E2E sono configurati in seriale (`workers: 1`) per evitare interferenze sullo stato partita condiviso. ## 6) Come leggere i risultati ### 6.1 Risultati Vitest Caso OK (verde): ```text Test Files 6 passed (6) Tests 159 passed (159) ``` Significa: - tutti i test Vitest sono passati Caso KO (rosso): - guarda prima il nome del file test - poi il nome del test (`describe/test`) - poi la riga con `expected` e `received` - infine vai alla riga indicata nello stack trace ### 6.2 Risultati Playwright Caso OK: ```text 72 passed ``` Caso KO: - apri il report HTML ```bash npx playwright show-report ``` Nel report puoi vedere: - step del test - errori precisi - screenshot/diff - trace ## 7) Visual Regression (screenshot) I test visual confrontano immagini attuali con immagini baseline. Cartella baseline: - `tests/e2e/visual-regression.spec.cjs-snapshots/` Se cambia la UI in modo intenzionale: - aggiorna snapshot ```bash npm run test:e2e -- --update-snapshots ``` Poi rilancia controllo: ```bash npm run test:e2e ``` Se la UI non doveva cambiare: - non aggiornare snapshot - correggi prima il codice UI/CSS ## 8) Errori comuni e soluzione veloce - Errore Playwright `Executable doesn't exist`: - esegui `npx playwright install chromium firefox` - E2E instabili con punteggi strani: - assicurati che i test restino seriali (`workers: 1`) - assicurati che ogni test parta da stato pulito (reset) - Selettore ambiguo (esempio bottone `Cambi`): - usa selector piu specifici, ad esempio `getByRole(..., { exact: true })` - Failure accessibilita: - controlla prima `alt` delle immagini e contrasto colori ## 9) Mini checklist prima di fare push Esegui: ```bash npm run test:all npm run test:e2e ``` Se hai cambiato UI e i visual falliscono per differenze volute: ```bash npm run test:e2e -- --update-snapshots npm run test:e2e ``` ## 10) Come aggiungere un nuovo test (consigli pratici) - metti i test nel posto giusto: - `tests/unit` per logica pura - `tests/integration` per moduli che dialogano - `tests/component` per Vue in isolamento - `tests/stress` per carico - `tests/e2e` per flussi reali - mantieni nomi chiari: - il titolo del test deve spiegare cosa verifica - evita test dipendenti da ordine: - ogni test deve potersi eseguire da solo - negli E2E: - porta sempre il sistema in stato iniziale - usa selector robusti - limita `waitForTimeout` e preferisci attese su condizioni reali Se segui questi punti, i test restano stabili e facili da capire anche per chi entra ora nel progetto.