# 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 ```mermaid 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.