diff --git a/piano-generazione-test.md b/piano-generazione-test.md new file mode 100644 index 0000000..f8470eb --- /dev/null +++ b/piano-generazione-test.md @@ -0,0 +1,159 @@ +# 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. diff --git a/seo_pwa_strategy.md b/seo_pwa_strategy.md new file mode 100644 index 0000000..1f7c463 --- /dev/null +++ b/seo_pwa_strategy.md @@ -0,0 +1,184 @@ +# Strategia SEO e Indicizzazione per la PWA dei Canti + +Questo documento definisce la strategia tecnica per consentire l'indicizzazione dei testi dei canti da parte dei motori di ricerca (in particolare Googlebot) e la corretta generazione delle anteprime (social cards) su piattaforme di messaggistica e social media (WhatsApp, Telegram, Facebook, ecc.), mantenendo intatta l'architettura PWA (Progressive Web App) offline-ready. + +--- + +## 1. Il Contesto Tecnologico +L'applicazione è sviluppata con: +- **Angular 20** (Framework Core) +- **Ionic 8** (UI & Routing integration) +- **Angular Service Worker (`@angular/service-worker`)** per le funzionalità offline della PWA. + +--- + +## 2. La Strategia Selezionata: Prerendering / Static Site Generation (SSG) + +Dato che i testi dei canti sono **dati statici** (non cambiano in base all'utente connesso e variano molto raramente), la soluzione ottimale è la **Static Site Generation (SSG)**, nota anche come **Prerendering**. + +### Come Funziona la Sinergia SSG + PWA +1. **Fase di Build:** Durante la compilazione dell'app (`ng build`), Angular genera un file `index.html` statico e pre-renderizzato per ogni singolo canto (es. `/canti/tu-sei-sorgente/index.html`). +2. **Scansione dello Spider (SEO):** Quando Googlebot o i crawler dei social richiedono l'URL di un canto, il server o la CDN distribuiscono immediatamente il file HTML statico già popolato con il testo del canto e con i meta tag corretti. +3. **Idratazione e PWA (Client):** Quando un utente apre la pagina sul browser, Angular scarica i bundle JavaScript ed esegue l'**hydration** in background. L'applicazione "prende vita" come Single Page Application (SPA), attiva il Service Worker e abilita la navigazione offline e l'installabilità come PWA. + +--- + +## 3. Fasi e Dettagli di Implementazione + +### Fase 1: Struttura degli URL e Routing Semantico +Per facilitare la SEO, gli URL devono essere parlanti e privi di simboli di hash (`#`). Attualmente, l'applicazione utilizza già il routing basato su percorsi standard (PathLocationStrategy) in [app-routing.module.ts](file:///Users/davidfrassi/SRC/agenti/canti/src/app/app-routing.module.ts). + +È necessario definire una rotta dedicata per i singoli canti che accetti un parametro semantico (detto *slug* o *alias*), ad esempio: + +```typescript +// src/app/app-routing.module.ts +const routes: Routes = [ + // ... altre rotte + { + path: 'canti/:slug', + loadChildren: () => import('./pages/canto-detail/canto-detail.module').then(m => m.CantoDetailPageModule) + } +]; +``` + +I collegamenti all'interno dell'applicazione per navigare verso i canti devono utilizzare il tag semantico `` con la direttiva `routerLink`, per consentire a Googlebot di scoprire autonomamente tutte le pagine: + +```html + +... + + + + {{ canto.titolo }} + +``` + +--- + +### Fase 2: Gestione dei Meta Tag Dinamici +Ogni canto deve avere un titolo e una descrizione univoci e ottimizzati per la SEO. In Angular si utilizzano i servizi `Title` e `Meta` di `@angular/platform-browser` per aggiornare i metadati all'inizializzazione del componente: + +```typescript +// src/app/pages/canto-detail/canto-detail.page.ts +import { Component, OnInit } from '@angular/core'; +import { ActivatedRoute } from '@angular/router'; +import { Title, Meta } from '@angular/platform-browser'; +import { CantiService } from '../../services/canti.service'; + +@Component({ + selector: 'app-canto-detail', + templateUrl: './canto-detail.page.html', + styleUrls: ['./canto-detail.page.scss'], +}) +export class CantoDetailPage implements OnInit { + canto: any; + + constructor( + private route: ActivatedRoute, + private cantiService: CantiService, + private titleService: Title, + private metaService: Meta + ) {} + + ngOnInit() { + const slug = this.route.snapshot.paramMap.get('slug'); + if (slug) { + this.canto = this.cantiService.getCantoBySlug(slug); + this.updateSEOMetadata(); + } + } + + updateSEOMetadata() { + const titoloCompleto = `${this.canto.titolo} - Canti Cristiani`; + const descrizione = `Testo e accordi del canto "${this.canto.titolo}". ${this.canto.testo.substring(0, 150)}...`; + + // Imposta il titolo della pagina + this.titleService.setTitle(titoloCompleto); + + // Imposta i meta tag standard per la SEO + this.metaService.updateTag({ name: 'description', content: descrizione }); + + // Imposta i tag OpenGraph per la condivisione sui social (Facebook, WhatsApp, Telegram) + this.metaService.updateTag({ property: 'og:title', content: titoloCompleto }); + this.metaService.updateTag({ property: 'og:description', content: descrizione }); + this.metaService.updateTag({ property: 'og:type', content: 'article' }); + this.metaService.updateTag({ property: 'og:url', content: `https://canti.cristiani.it/canti/${this.canto.slug}` }); + + // Se c'è un'immagine associata o una copertina di default + this.metaService.updateTag({ property: 'og:image', content: 'https://canti.cristiani.it/assets/og-cover.png' }); + } +} +``` + +--- + +### Fase 3: Configurazione del Prerendering (SSG) in Angular 20 +In Angular 20, l'abilitazione del server-side rendering e del prerendering statico durante la compilazione avviene aggiungendo il pacchetto SSR ufficiale: + +```bash +ng add @angular/ssr +``` + +Questo comando configura automaticamente l'applicazione modificando `angular.json` e creando i file necessari per la compilazione lato server. + +#### Configurazione delle rotte da pre-renderizzare +Poiché l'elenco dei canti è dinamico (es. risiede in file JSON o database), dobbiamo indicare ad Angular quali rotte generare staticamente durante il comando `ng build`. + +Si crea un file di configurazione per definire le rotte o si utilizza uno script per estrarle dinamicamente: + +1. **Creare un file delle rotte statiche** `prerender-routes.txt`: + ```txt + /home + /settings + /canti/tu-sei-sorgente + /canti/re-dei-re + /canti/lodi-al-altissimo + ``` +2. **Automatizzare la generazione di questo file** inserendo uno script (es. `generate-routes.js`) da eseguire prima della build che legge l'elenco dei canti dal file JSON locale e scrive l'elenco dei percorsi in `prerender-routes.txt`. +3. **Configurare `angular.json`** per consumare questo file: + ```json + "prerender": { + "discoverRoutes": false, + "routesFile": "prerender-routes.txt" + } +``` + +Al termine della build (`npm run build`), nella cartella di distribuzione (es. `dist/canticristiani/browser`) verranno generate cartelle fisiche con i file `index.html` pronti all'uso per ciascuna rotta definita. + +--- + +### Fase 4: Sitemap.xml e Robots.txt +Per garantire che Googlebot trovi tempestivamente tutti i canti, è fondamentale generare un file `sitemap.xml` da posizionare nella radice del server web. + +#### Esempio di `sitemap.xml`: +```xml + + + + https://canti.cristiani.it/home + weekly + 1.0 + + + + https://canti.cristiani.it/canti/tu-sei-sorgente + monthly + 0.8 + + +``` + +#### Esempio di `robots.txt`: +```txt +User-agent: * +Allow: / + +Sitemap: https://canti.cristiani.it/sitemap.xml +``` + +--- + +## 4. Vantaggi e Risultati Attesi +- **Indicizzazione immediata:** Googlebot indicizzerà i testi dei canti all'istante, consentendo agli utenti di trovare la PWA cercando frammenti di testo o il titolo del canto direttamente su Google. +- **Anteprime nei Social Perfette:** La condivisione dei link sui canali di comunicazione mostrerà anteprime ricche (titolo corretto, frammento del testo del canto e logo dell'app). +- **Integrità PWA:** L'utente beneficerà di un caricamento iniziale ultra-veloce (grazie all'HTML pre-renderizzato) seguito dall'installazione offline e dall'esperienza fluida tipica dell'applicazione mobile.