canti/piano-generazione-test.md

Piano delle Azioni per la Generazione di una Batteria di Test (.spec.ts)

Questo documento descrive in dettaglio la strategia, l'analisi dello stato attuale e l'elenco delle azioni sequenziali necessarie per implementare una suite completa di test unitari e di integrazione per tutte le classi (servizi, pagine e componenti) dell'applicazione Angular/Ionic.

---

📊 Analisi dello Stato Attuale dei Test

L'applicazione utilizza Angular v20, Ionic v8, e il framework di test standard Jasmine abbinato al test runner Karma.

Un'analisi del codice ha rilevato la seguente situazione per ciascun componente chiave:

1. Servizi (src/app/services)

I servizi gestiscono la logica di business fondamentale (audio, sincronizzazione, storage, stato).

• ❌ audio-engine.service.ts — Nessun test
• ❌ canti-letture.service.ts — Nessun test
• ❌ canti.service.ts — Nessun test
• ❌ comunita.service.ts — Nessun test
• ❌ connectivity.service.ts — Nessun test
• ❌ lyrics-parser.service.ts — Nessun test
• ❌ media-session.service.ts — Nessun test
• ⚠️ my-canti.service.ts — Spec esistente ma corrotto/obsoleto (my-canti.spec.ts fa riferimento a una classe MyCanti che non esiste, la classe reale è MyCantiService).
• ❌ playlist.service.ts — Nessun test
• ❌ settings.service.ts — Nessun test
• ❌ stats.service.ts — Nessun test
• ❌ theme.service.ts — Nessun test
• ❌ youtube-player.service.ts — Nessun test

2. Pagine (src/app/pages & src/app/home)

Le pagine gestiscono la visualizzazione e l'interazione con l'utente.

• ⚠️ home.page.ts — Spec esistente (home.page.spec.ts) ma limitato al boilerplate base (verifica solo la creazione).
• ⚠️ display.page.ts — Spec esistente (display.page.spec.ts) solo boilerplate base.
• ⚠️ player.page.ts — Spec esistente (player.page.spec.ts) solo boilerplate base.
• ❌ playlist.page.ts — Nessun test
• ⚠️ propose-canto.page.ts — Spec esistente (propose-canto.page.spec.ts) solo boilerplate base.
• ❌ settings.page.ts — Nessun test

3. Componenti (src/app/components)

• ❌ qr-scanner/qr-scanner.component.ts — Nessun test

---

🛠️ Strategia di Mocking e Test in Angular/Ionic

Per testare efficacemente queste classi in isolamento, definiremo una strategia di mocking standard:

1. Storage di Ionic (@ionic/storage-angular): Molti servizi (MyCantiService, SettingsService, ComunitaService) dipendono dallo Storage. Creeremo un mock per simulare i metodi get, set e remove usando una mappa in memoria.
2. Controller di Ionic (ToastController, ModalController, AlertController): Utilizzeremo jasmine.createSpyObj per simulare la creazione e la presentazione dei componenti UI di Ionic senza istanziarli realmente nel DOM durante i test dei servizi.
3. Ambiente HTML5 (Audio, Window): Servizi come AudioEngineService e YoutubePlayerService interagiscono con le API audio del browser e l'oggetto window. Useremo dei mock o spy su Audio, window.location, ecc.

---

🚀 Elenco Dettagliato delle Azioni da Compiere

Le azioni sono suddivise in 6 fasi logiche per garantire un approccio sistematico e sicuro.

Fase 1: Verifica dell'Ambiente e Correzione dei Test Esistenti

Prima di scrivere nuovi test, dobbiamo assicurarci che l'infrastruttura di test esistente sia stabile e funzionante.

• Azione 1.1: Esecuzione iniziale dei test
  • Eseguire npm run test (o ng test --watch=false) per verificare se la suite iniziale compila ed è verde.
• Azione 1.2: Correzione di my-canti.spec.ts
  • Rinominare il file in my-canti.service.spec.ts per uniformità.
  • Correggere gli import: importare MyCantiService anziché MyCanti.
  • Configurare il TestBed fornendo il mock per Storage, CantiService e ToastController.
  • Verificare che il test passi con successo.
• Azione 1.3: Aggiornamento dei boilerplate delle pagine esistenti
  • Risolvere eventuali errori nei test pregenerati (home.page.spec.ts, display.page.spec.ts, player.page.spec.ts, propose-canto.page.spec.ts) fornendo i moduli minimi (IonicModule, RouterTestingModule) e i mock dei servizi iniettati nei loro costruttori.

---

Fase 2: Implementazione dei Test sui Servizi (Core Logico)

I servizi sono la priorità in quanto non hanno dipendenze grafiche complesse e contengono la logica di business principale.

• Azione 2.1: Test per connectivity.service.ts e theme.service.ts
  • Perché: Sono i più semplici e privi di dipendenze esterne pesanti.
  • Test: Cambiamenti di stato della rete online/offline, applicazione corretta delle classi CSS per i temi (scuro/chiaro).
• Azione 2.2: Test per lyrics-parser.service.ts
  • Casi di test: Parsing corretto dei testi dei canti con accordi tra parentesi (es. [Do]), gestione delle righe vuote, estrazione del testo pulito, formattazione.
• Azione 2.3: Test per settings.service.ts
  • Casi di test: Caricamento delle impostazioni di default da storage, salvataggio di nuove impostazioni, gestione del cambio di dimensione del testo, export/import delle impostazioni.
• Azione 2.4: Test per stats.service.ts
  • Casi di test: Incremento delle statistiche di visualizzazione di un canto, persistenza su storage, generazione dei report dei canti più cantati.
• Azione 2.5: Test per canti.service.ts e canti-letture.service.ts
  • Casi di test: Lettura del database dei canti, filtri di ricerca per titolo/testo/momento liturgico, associazione tra letture del giorno e canti consigliati (sulla base delle strategie liturgiche descritte in liturgia_strategy.md).
• Azione 2.6: Test per comunita.service.ts
  • Casi di test: Gestione del codice comunità, sincronizzazione dei canti della comunità tramite chiamate HTTP (mocking di HttpClient), salvataggio in storage locale.
• Azione 2.7: Test per playlist.service.ts
  • Casi di test: Creazione, modifica e cancellazione di playlist, riordino dei canti all'interno di una playlist, salvataggio e ripristino da storage.
• Azione 2.8: Test per media-session.service.ts
  • Casi di test: Integrazione con l'API navigator.mediaSession del browser, aggiornamento dei metadati audio (titolo, autore, copertina), gestione degli eventi di riproduzione/pausa del sistema operativo.
• Azione 2.9: Test per audio-engine.service.ts e youtube-player.service.ts
  • Casi di test: Avvio, pausa, stop e seek delle tracce audio locali e dei video YouTube, gestione degli eventi di fine riproduzione, aggiornamento dello stato tramite Signals/RxJS.

---

Fase 3: Implementazione dei Test sui Componenti Condivisi

• Azione 3.1: Test per qr-scanner.component.ts
  • Casi di test: Inizializzazione della fotocamera, gestione dei permessi negati, decodifica del codice QR (simulando l'evento del decoder), emissione del codice scansionato tramite @Output(), interruzione dello streaming video alla distruzione del componente.

---

Fase 4: Implementazione e Arricchimento dei Test sulle Pagine (UI & Controller)

Qui testeremo l'integrazione tra i servizi (mockati) e l'interfaccia utente di Ionic.

• Azione 4.1: Test approfonditi per home.page.ts
  • Casi di test: Visualizzazione dell'elenco dei canti, funzionamento della barra di ricerca (filtro istantaneo), apertura dei dettagli del canto, gestione della navigazione verso le altre pagine.
• Azione 4.2: Test approfonditi per player.page.ts
  • Casi di test: Interazione con i pulsanti di play/pause, scorrimento del testo a tempo, trasposizione degli accordi (es. +1 semitono, -1 semitono) con aggiornamento dinamico del testo a schermo.
• Azione 4.3: Test approfonditi per display.page.ts
  • Casi di test: Rendering corretto del testo del canto, applicazione del tema visivo e della dimensione del font dalle impostazioni, gestione del blocco dello spegnimento dello schermo (se implementato).
• Azione 4.4: Creazione e test per playlist.page.ts
  • Casi di test: Visualizzazione dell'elenco delle playlist dell'utente, creazione di una nuova playlist tramite popup, aggiunta di canti, eliminazione di canti con swipe.
• Azione 4.5: Test approfonditi per propose-canto.page.ts
  • Casi di test: Validazione del form di proposta (titolo obbligatorio, testo minimo), generazione della mailto URL corretta con il body in formato JSON, comportamento del pulsante di invio.
• Azione 4.6: Creazione e test per settings.page.ts
  • Casi di test: Toggle del tema scuro (con verifica dell'applicazione al DOM), selezione della dimensione del font, reset dei dati locali con richiesta di conferma tramite AlertController.

---

Fase 5: Raccolta delle Metriche di Coverage e Rifinitura

• Azione 5.1: Configurazione del report di coverage
  • Assicurarsi che karma.conf.js sia configurato per esportare i dati in formato lcov o html (tramite karma-coverage).
• Azione 5.2: Generazione del report
  • Eseguire ng test --code-coverage --watch=false.
  • Esaminare la cartella coverage/ generata per individuare eventuali rami logici (branches) o righe non coperte nei servizi core.
• Azione 5.3: Incremento mirato del coverage
  • Aggiungere test specifici per coprire i casi limite (edge cases) e la gestione degli errori (es. fallimento delle chiamate HTTP, storage corrotto).

---

Fase 6: Automazione in CI/CD (Opzionale ma Consigliato)

• Azione 6.1: Configurazione test headless
  • Configurare Karma per eseguire i test in modalità headless usando ChromeHeadless su sistemi di Continuous Integration (es. GitHub Actions).
  • Aggiungere uno script npm test:ci: "test:ci": "ng test --watch=false --browsers=ChromeHeadless".

---

📈 Tabella di Marcia Consigliata

gantt
    title Roadmap per la Copertura dei Test
    dateFormat  YYYY-MM-DD
    section Fase 1
    Verifica & Fix Esistenti :active, 2026-05-21, 2d
    section Fase 2
    Test Servizi Core        : 2026-05-23, 5d
    section Fase 3 & 4
    Test Componenti & Pagine : 2026-05-28, 5d
    section Fase 5 & 6
    Coverage & CI/CD         : 2026-06-02, 2d

Tip

Consiglio per l'efficienza: Si raccomanda di iniziare ad implementare i test partendo dai servizi a più basso livello (come ConnectivityService, ThemeService, LyricsParserService) perché sono privi di dipendenze e consentono di stabilire rapidamente dei pattern di test solidi prima di affrontare servizi più complessi o interfacce grafiche.