attilio/segnapunti
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(tests): riscrive la guida test con approccio per principianti

Browse Source 
- 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
This commit is contained in:
Davide Grilli
2026-02-12 19:35:22 +01:00
parent 33e2583b4d
commit e4d212eea3
1 changed files with 238 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

364
tests/README.md
View File

@@ -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.