From e4d212eea3ecf0c0f0d2a1a28341d51b0c8a00e7 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 12 Feb 2026 19:35:22 +0100 Subject: [PATCH] docs(tests): riscrive la guida test con approccio per principianti - spiega obiettivi e differenze tra unit, integration, component, stress ed E2E - aggiunge istruzioni passo-passo per esecuzione e lettura risultati - documenta gestione snapshot visual e troubleshooting errori comuni - include checklist pratica pre-push --- tests/README.md | 364 +++++++++++++++++++++++++++++++----------------- 1 file changed, 238 insertions(+), 126 deletions(-) diff --git a/tests/README.md b/tests/README.md index 8d1bf11..87127a6 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,169 +1,281 @@ -# Guida ai Test per Principianti - Segnapunti +# Guida ai Test -Benvenuto nella guida ai test del progetto! +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 -Questo progetto usa tre tipi di test: +## 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 veloci per logica pura (funzioni, classi) -├── integration/ # Test per componenti che interagiscono (es. WebSocket) -├── e2e/ # Test simil-utente reale (Controller -> Display flux) -└── README.md # Questa guida +├── 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 ``` -1. **Test Unitari (unit) (Vitest)**: Si occupano di verificare le singole funzioni, i componenti e la logica di business in isolamento. Sono progettati per essere estremamente veloci e fornire un feedback immediato sulla correttezza del codice durante lo sviluppo, garantendo che ogni piccola parte del sistema funzioni come previsto. -2. **Test di Integrazione (integration) (Vitest)**: Verificano che diversi moduli o servizi (come la comunicazione tramite WebSocket tra server e client) funzionino correttamente insieme, garantendo che i messaggi e gli eventi vengano scambiati e gestiti come previsto. -3. **Test End-to-End (E2E) (Playwright)**: Questi test simulano il comportamento di un utente reale all'interno di un browser (come Chrome o Firefox). Verificano che l'intera applicazione funzioni correttamente dall'inizio alla fine, testando l'interfaccia utente, le API e il database insieme per assicurarsi che i flussi principali (come la creazione di una partita) non presentino errori. +## 2) Tecnologie usate ---- +- `Vitest`: per `unit`, `integration`, `component`, `stress` +- `Playwright`: per `e2e` -## 1. Come eseguire i Test Veloci (Unit) +Tradotto in modo semplice: +- Vitest controlla parti interne del progetto +- Playwright controlla il comportamento reale dell'app nel browser -Questi test controllano che la logica interna del server funzioni correttamente. +## 3) Prerequisiti (prima di tutto) -### Cosa viene testato? +### 3.1 Installa dipendenze -#### `gameState.test.js` (Logica di Gioco) - -- **Punteggio**: Verifica che i punti aumentino correttamente (0 -> 1). -- **Cambio Palla**: Controlla che il servizio passi all'avversario e che la formazione ruoti. -- **Vittoria Set**: - - Verifica la vittoria a 25 punti. - - Verifica la regola dei vantaggi (si vince solo con 2 punti di scarto, es. 26-24). -- **Reset**: Controlla che il tasto Reset azzeri punti, set e formazioni. - -#### `server-utils.test.js` (Utility) - -- **Stampa Info**: Verifica che il server stampi gli indirizzi IP corretti all'avvio. - -### Comando - -Apri il terminale nella cartella del progetto e scrivi: +Dalla root del progetto: ```bash -npm run test:unit +npm install ``` -### Cosa succede se va tutto bene? - -Vedrai delle scritte verdi con la spunta `✓`. -Esempio: - -``` - ✓ tests/unit/server-utils.test.js (1 test) - Test Files 1 passed (1) - Tests 1 passed (1) -``` - -Significa che il codice funziona come previsto! - -### Cosa succede se c'è un errore? - -Vedrai delle scritte rosse `×` e un messaggio che ti dice cosa non va. -Esempio: - -``` - × tests/unit/server-utils.test.js > Server Utils > ... - AssertionError: expected 'A' to include 'B' -``` - -Significa che hai rotto qualcosa nel codice. Leggi l'errore per capire dove (ti dirà il file e la riga). - ---- - -## 2. Come eseguire i Test di Integrazione (Integration) - -Questi test verificano che i componenti del sistema comunichino correttamente tra loro (es. il Server e i Client WebSocket). - -### Cosa viene testato? - -#### `websocket.test.js` (Integrazione WebSocket) - -- **Registrazione**: Verifica che un client riceva lo stato del gioco appena si collega. -- **Flusso Messaggi**: Controlla che quando il Controller invia un comando, il Server lo riceva e lo inoltri a tutti (es. Display). -- **Sicurezza**: Assicura che solo il "Controller" possa cambiare i punti (il "Display" non può inviare comandi di modifica). - -### Comando - -I test di integrazione sono eseguiti insieme agli unit test: +### 3.2 Installa browser Playwright (solo E2E) ```bash -npm run test:unit +npx playwright install chromium firefox ``` -*(Se vuoi eseguire solo gli integrazione, puoi usare `npx vitest tests/integration`)* +Se non fai questo passo, gli E2E possono fallire subito con errore tipo: +- `Executable doesn't exist` -### Cosa succede se va tutto bene? - -Come per gli unit test, vedrai delle spunte verdi `✓` anche per i file nella cartella `tests/integration/`. - -### Cosa succede se c'è un errore? - -Vedrai un errore simile agli unit test, ma spesso legato a problemi di comunicazione (es. "expected message not received"). - ---- - -## 3. Come eseguire i Test Completi (E2E) - -Questi test simulano un utente che apre il sito. Il computer farà partire il server, aprirà un browser invisibile (o visibile) e proverà a usare il sito come farebbe una persona. - -### Cosa viene testato? - -#### `game-simulation.spec.js` (Simulazione Partita) - -Un "robot" esegue queste azioni automaticamente: - -1. Apre il **Display** e il **Controller** in due schede diverse. -2. Premi **Reset** per essere sicuro di partire da zero. -3. Clicca **25 volte** sul tasto "+" del Controller. -4. Controlla che sul **Display** appaia che il set è stato vinto (Punteggio Set: 1). - -### Comando +## 4) Comandi principali ```bash -npm run test:e2e +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 ``` -(Oppure `npx playwright test` per maggiori opzioni) +Ordine consigliato (quando vuoi verificare tutto): +1. `npm run test:all` +2. `npm run test:e2e` -### Cosa succede se va tutto bene? +## 5) Cosa testa ogni suite (spiegato semplice) -Il test impiegherà qualche secondo (è più lento degli unit test). Se tutto va bene, vedrai: +### 5.1 Unit (`tests/unit`) -``` -Running 1 test using 1 worker - ✓ 1 [chromium] › tests/e2e/game-simulation.spec.js:3:1 › Game Simulation (5.0s) - 1 passed (5.5s) +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 che il sito si apre correttamente e il flusso di gioco funziona dall'inizio alla fine! +Significa: +- tutti i test Vitest sono passati -### Cosa succede se c'è un errore? +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 -Se qualcosa non va (es. il server non parte, o il controller non aggiorna il display), il test fallirà. -Playwright genererà un **Report HTML** molto dettagliato. -Per vederlo, scrivi: +### 6.2 Risultati Playwright + +Caso OK: + +```text +72 passed +``` + +Caso KO: +- apri il report HTML ```bash npx playwright show-report ``` -Si aprirà una pagina web dove potrai vedere passo-passo cosa è successo, inclusi screenshot e video dell'errore. +Nel report puoi vedere: +- step del test +- errori precisi +- screenshot/diff +- trace ---- +## 7) Visual Regression (screenshot) -## Domande Frequenti +I test visual confrontano immagini attuali con immagini baseline. -**Q: I test E2E falliscono su WebKit (Safari)?** -A: È normale su Linux se non hai installato tutte le librerie di sistema. Per ora testiamo solo su **Chromium** (Chrome) e **Firefox** che sono più facili da far girare. +Cartella baseline: +- `tests/e2e/visual-regression.spec.cjs-snapshots/` -**Q: Devo avviare il server prima dei test?** -A: No! Il comando `npm run test:e2e` avvia automaticamente il tuo server (`npm run serve`) prima di iniziare i test. +Se cambia la UI in modo intenzionale: +- aggiorna snapshot -**Q: Come creo un nuovo test?** -A: +```bash +npm run test:e2e -- --update-snapshots +``` -- **Unit**: Crea un file `.test.js` in `tests/unit/`. Copia l'esempio esistente. -- **Integration**: Crea un file `.test.js` in `tests/integration/`. -- **E2E**: Crea un file `.spec.js` in `tests/e2e/`. Copia l'esempio esistente. +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.