segnapunti/tests/README.md

# Guida ai Test per Principianti - Segnapunti

Benvenuto nella guida ai test del progetto!

Questo progetto usa tre tipi di 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
```

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:

```bash
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:

```bash
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

```bash
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:

```bash
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.