segnapunti/tests/README.md

Guida ai Test per Principianti - Segnapunti

Benvenuto nella guida ai test del progetto!

Questo progetto usa tre tipi di test:

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

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.

---

1. Come eseguire i Test Veloci (Unit)

Questi test controllano che la logica interna del server funzioni correttamente.

Cosa viene testato?

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:

npm run test:unit

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:

npm run test:unit

(Se vuoi eseguire solo gli integrazione, puoi usare npx vitest tests/integration)

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

npm run test:e2e

(Oppure npx playwright test per maggiori opzioni)

Cosa succede se va tutto bene?

Il test impiegherà qualche secondo (è più lento degli unit test). Se tutto va bene, vedrai:

Running 1 test using 1 worker
  ✓  1 [chromium] › tests/e2e/game-simulation.spec.js:3:1 › Game Simulation (5.0s)
  1 passed (5.5s)

Significa che il sito si apre correttamente e il flusso di gioco funziona dall'inizio alla fine!

Cosa succede se c'è un errore?

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:

npx playwright show-report

Si aprirà una pagina web dove potrai vedere passo-passo cosa è successo, inclusi screenshot e video dell'errore.

---

Domande Frequenti

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.

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.

Q: Come creo un nuovo test?
A:

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