siae-automation

SIAE Automation — E2E Test Generation & Xray Sync

╔══════════════════════════════════════════════════════════════════╗
║    ███████╗██╗ █████╗ ███████╗    ██████╗ ███████╗██╗   ██╗      ║
║    ██╔════╝██║██╔══██╗██╔════╝    ██╔══██╗██╔════╝██║   ██║      ║
║    ███████╗██║███████║█████╗      ██║  ██║█████╗  ██║   ██║      ║
║    ╚════██║██║██╔══██║██╔══╝      ██║  ██║██╔══╝  ╚██╗ ██╔╝      ║
║    ███████║██║██║  ██║███████╗    ██████╔╝███████╗ ╚████╔╝       ║
║    ╚══════╝╚═╝╚═╝  ╚═╝╚══════╝    ╚═════╝ ╚══════╝  ╚═══╝        ║
║              🔨 DevForge · AI Competence Center                  ║
║         "Il codice si forgia. Il developer cresce."              ║
╚══════════════════════════════════════════════════════════════════╝

Tipo: Rigid | Fase SDLC: 5. Testing / Automation

---

LA LEGGE DI FERRO

NESSUN TEST AUTOMATIZZATO SENZA LISTA TC CONFERMATA DAL DEVELOPER

Stai per generare test E2E senza la lista TC confermata dal developer? FERMATI. La proposta ROI e' un suggerimento — la conferma esplicita e' obbligatoria.

Stai per automatizzare TUTTI i TC senza valutare il ROI? FERMATI. Automatizzare TC con 15 step o logica ambigua genera test fragili che si rompono a ogni release. Il ROI serve per scegliere cosa vale la manutenzione.

Stai per procedere senza cercare la TL esistente in Xray? FERMATI. Una TL potrebbe esistere da un sprint precedente. Non sovrascrivere lavoro fatto.

---

📊 Dai repo itsiae: I repo con test E2E automatizzati rilevano il 67% dei bug di regressione prima del deploy in collaudo. Fonte: analisi su 816 repository GitHub itsiae (60 Java, 44 HCL, 23 Python, 22 TypeScript).

QUANDO SI APPLICA

• Dopo siae-qa: la skill ha prodotto la Test List — questa skill decide quali TC automatizzare e genera i test E2E
• Invocazione manuale via trigger sentence: anche su TL già esistenti in Xray
• Su TL pre-esistente: se in Xray esiste già una Test List per la Story, la skill la legge e propone cosa aggiungere o automatizzare

---

RILEVAMENTO CANALE

Prima di qualsiasi altra operazione, rileva il canale analizzando i file nella directory:

Segnale rilevato	Canale
.xcworkspace, *.xcodeproj, ios/	Mobile — iOS
android/, *.apk, google-services.json	Mobile — Android
app.json, capacitor.config.ts	Mobile — cross-platform
cypress.config.ts, cypress.config.js, cypress/	Web — Cypress
package.json con dipendenza "cypress"	Web — Cypress

Se il progetto ha segnali di entrambi i canali, chiedi al developer quale automatizzare in questa sessione. Se nessun segnale, chiedi: "Stai automatizzando una app mobile (iOS/Android) o un'applicazione web?"

---

LIVELLI DI INTEGRAZIONE

Tier	Condizione	Comportamento
Tier 1	MCP Atlassian disponibile	Legge TL da Xray, crea/aggiorna Test Execution, sync risultati automatico
Tier 2	appium-mcp o Cypress disponibili, no MCP Atlassian	TL fornita manualmente o da CSV siae-qa, genera test, sync manuale
Tier 3	Nessuna integrazione	Genera test E2E e CSV per import manuale in Xray

---

PRE-FLIGHT CARD DI APERTURA

🟡 MEDIO (reversibile) — 🔨 DevForge · siae-automation
📱 Canale: Mobile iOS / Mobile Android / Web · 📡 Tier: Tier 1 / 2 / 3
🎫 TL Xray: XP-XXX / Non trovata / Da CSV · 🔢 TC totali TL: N TC
🤖 appium-mcp: Disponibile / Non disponibile · ☁️ BrowserStack: Configurato / Mancante · 🔄 Xray sync: MCP / CSV
▼ Azione
💡 Perche': Leggo prima la TL, poi propongo il piano automation
🚫 Se NO: Workflow automation non inizia

---

WORKFLOW A 5 FASI

Fase 1 — Ricerca Test List e mappatura chiavi Xray

Obiettivo: ottenere la Test List (TC con chiavi Jira reali) per questa Story e verificare se esiste già una Test Execution di automation. Non assumere che né la TL né la TE esistano. Cercale sempre prima.

Tier 1 (MCP Atlassian):

Le funzioni JQL specifiche di Xray (es. testPlanWith(), testSetsOf()) sono disponibili solo in Xray Server, non in Xray Cloud. In Xray Cloud usa Jira JQL standard:

1. Cerca il Test Plan per nome e sprint:

   JQL: issueType = "Test Plan"
        AND summary ~ "{Story summary o STORY_ID}"
        AND sprint = "{sprint corrente}"
   

   Se non trovi nulla: cerca più ampio:

   JQL: issueType = "Test Plan" AND summary ~ "{STORY_ID}"
   

2. Se il Test Plan non è trovato via JQL: chiedi al developer la chiave diretta (es. XP-123). Non insistere con JQL — in Xray Cloud i Test Plan non sono sempre linkati alla Story via campo standard.

3. Se il Test Plan esiste: leggi i TC collegati (ID Jira reale, summary, Automazione, NRT, step).

   • Distingui TC già marcati Automazione=Y da quelli con Automazione=N.

4. Cerca Test Execution automation già esistenti:

   JQL: issueType = "Test Execution" AND summary ~ "[AUTOMATION]" AND sprint = "{sprint}"
   

   • Se esiste: non creare duplicati. Aggiornala con i nuovi TC confermati.
   • Se non esiste: sarà creata in Fase 4.W0 (web) o Fase 5 (mobile).

Tier 3 (no MCP) — input manuale con mappatura chiavi:

Chiedi al developer:

"Hai già importato i TC in Xray dalla sessione siae-qa? Se sì, ho bisogno della mappatura tra gli ID del CSV e le chiavi Jira assegnate da Xray."

Se ha la mappatura → raccoglila:

ID CSV → Chiave Xray    Scenario
1      → PROJ-456       Verifica login credenziali valide
2      → PROJ-457       [EDGE] Login campo vuoto
3      → PROJ-458       [NEG] Login password errata

Se non ha ancora importato il CSV → importa prima con siae-qa, poi torna qui. Se non ricorda le chiavi → chiedi di aprire Xray, filtrare per Story {STORY_ID} e comunicare le chiavi.

Questa mappatura è l'input critico della skill: senza le chiavi Jira reali, i titoli it() negli spec Cypress non possono matchare con Xray. Non procedere alla Fase 2 senza di essa.

Output atteso Fase 1:

TL trovata: XP-123 "Test Plan RIPART-847 Sprint 24"
  TC totali: N
  Con Automazione=Y: N  ← già flaggati da siae-qa
  Con Automazione=N: N  ← candidati da valutare per ROI

Mappatura chiavi disponibile:
  1 → PROJ-456   Verifica login credenziali valide
  2 → PROJ-457   [EDGE] Login campo vuoto
  ...

Test Execution automation esistente: [XE-456] / Non trovata

---

Fase 2 — Analisi ROI e proposta lista automation

Obiettivo: non automatizzare tutto — proporre cosa automatizzare basandosi su valore reale.

Per ogni TC nella TL (sia Y che N), calcola un punteggio ROI con questi criteri:

Criterio	Punti	Razionale
NRT = Y	+3	Gira ad ogni regressione — massimo beneficio da automation
Happy path (nessun prefisso)	+2	Il flusso principale deve sempre essere automatizzato
[EDGE] o [NEG]	+2	Edge case e negativi automatizzati rilevano regressioni silenziose
Step ≤ 5	+2	Basso costo di implementazione e manutenzione
Step 6–10	+1	Costo moderato
Step > 10	−1	Fragile, costoso da mantenere — valutare se scomporre
[PROFILO]	+1	Scenari multi-ruolo beneficiano dell'automazione ripetibile
Già Automazione=Y	+1	Il developer lo ha già identificato come candidato

Fasce ROI:

Punteggio	Fascia	Proposta
≥ 7	🟢 ALTO	Automatizza subito — priorità 1
4–6	🟡 MEDIO	Consigliato — buon ritorno
1–3	🔴 BASSO	Valuta con il developer — rischio manutenzione elevato
≤ 0	⛔ SCONSIGLIATO	Non automatizzare — costo > beneficio

Presenta la proposta al developer in forma tabellare:

Proposta automation — RIPART-847
────────────────────────────────────────────────────────────────────
  ID    Scenario                           Cat      Step  NRT  ROI
────────────────────────────────────────────────────────────────────
  TC-1  Verifica login credenziali valide  happy    3     Y    🟢 8
  TC-3  Email non inviata senza royalties  [NEG]    2     Y    🟢 7
  TC-2  PDF con importo totale e dettaglio happy    3     Y    🟡 6
  TC-4  Warning log senza email            [EDGE]   2     N    🟡 5
  TC-7  Login con profilo editore          [PROF]   5     N    🟡 4
  TC-9  Timeout invio email               [EDGE]   12    Y    🔴 2
────────────────────────────────────────────────────────────────────
  Pre-selezionati (Automazione=Y da siae-qa): TC-1, TC-2, TC-3, TC-4
  Nuovi candidati suggeriti:                  TC-7
  Sconsigliati:                               TC-9 (12 step, fragile)

Spiega brevemente perché i BASSO/SCONSIGLIATI non convengono. Non darlo per scontato.

---

Fase 3 — Raffinamento da parte del developer

Non procedere alla generazione senza conferma esplicita del developer.

Chiedi:

"Questa è la lista proposta. Puoi:

• Confermare la selezione così com'è
• Aggiungere TC che non sono in lista (dimmi ID e scenario)
• Rimuovere TC che non vuoi automatizzare ora
• Posticipare i MEDIO per questo sprint

Quando sei pronto, dimmi la lista finale e partiamo."

Il developer può aggiungere TC non presenti nella TL originale. In questo caso:

• Chiedi scenario e steps se non li conosci già
• Calcola il ROI e segnala se è basso prima di generare

Output atteso Fase 3 — lista confermata:

Lista automation confermata (N TC):
  ✅ TC-1 — Verifica login credenziali valide  [🟢 ALTO]
  ✅ TC-3 — Email non inviata senza royalties  [🟢 ALTO]
  ✅ TC-2 — PDF con importo totale e dettaglio [🟡 MEDIO]
  ✅ TC-7 — Login con profilo editore          [🟡 MEDIO — aggiunto dal developer]
  ⏸ TC-4 — Posticipato dal developer
  ⛔ TC-9 — Escluso (ROI basso, confermato dal developer)

---

Fase 4 — Traduzione TC → Test Prompt + Generazione test E2E

Questa fase ha due livelli:

1. Layer di traduzione (obbligatorio, uguale per tutti i canali): converte ogni TC confermato in un Test Prompt strutturato e canale-agnostico
2. Layer di generazione (canale-specifico): usa il Test Prompt per alimentare appium-mcp (mobile) o generare lo spec Cypress (web)

Il layer di traduzione è separato dal canale intenzionalmente: lo stesso TC può essere portato su mobile e web senza riscrivere nulla.

---

Step 4.0 — Layer di traduzione: TC → Test Prompt

Per ogni TC nella lista confermata, produci un Test Prompt strutturato nel seguente formato. Questo è l'output intermedio da cui entrambi i path (mobile e web) partono.

TEST PROMPT — {TC-ID}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Story:       {STORY_ID}
Scenario:    {Scenario (descrizione) dal TC Xray}
Categoria:   {happy path / [EDGE] / [NEG] / [PROFILO]}
Precondizioni: {condizioni iniziali implicite o esplicite}

Step 1
  Intent:    {navigate | tap | input | verify | scroll | read}
  Action:    "{testo Action dal TC}"
  Target:    "{elemento UI coinvolto — nome descrittivo}"
  Data:      "{dato di test, se presente nel campo Data}"
  Expected:  "{testo Expected Result dal TC}"

Step 2
  Intent:    {navigate | tap | input | verify | scroll | read}
  Action:    "{testo Action dal TC}"
  Target:    "{elemento UI coinvolto}"
  Data:      "{dato di test}"
  Expected:  "{testo Expected Result dal TC}"

[... ripeti per ogni step ...]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Regole di traduzione per il campo Intent:

Parole chiave nell'Action	Intent assegnato
aprire, navigare, andare, accedere, aprire l'app	navigate
toccare, premere, cliccare, selezionare, scegliere	tap
inserire, digitare, scrivere, compilare	input
verificare, controllare, confermare, assicurarsi	verify
scorrere, scrollare, swipe	scroll
leggere, vedere, visualizzare (senza assert esplicito)	read

Regole per il campo Target:

• Estrai dall'Action il nome dell'elemento UI coinvolto
• Usa un nome descrittivo in italiano (es. "pulsante Accedi", "campo username", "schermata home")
• Se l'Action non specifica l'elemento, chiedi al developer prima di procedere

Se un Expected Result è ambiguo (es. "la pagina si carica", "l'operazione va a buon fine"): chiedi al developer quale elemento concreto o testo visibile conferma l'esito. Non lasciare Expected vuoto.

Output atteso Step 4.0: un Test Prompt per ogni TC confermato. Mostrali tutti al developer prima di procedere ai path, in modo che possa correggerli se qualcosa è stato mal interpretato.

Chi converte: L'agent stesso prende il Test Prompt canale-agnostico e genera il codice specifico per il canale rilevato (Cypress per web, appium-mcp per mobile). La conversione avviene in Step 4, non in Step 4.0.

---

PATH MOBILE — Appium + BrowserStack App Automate

Vedi reference/automation-channels.md#path-mobile per steps dettagliati (upload APK/IPA, mapping Intent→tool call appium-mcp, gestione sessioni).

Sintesi: start_session → launch_app → sequenza tool call per ogni step del Test Prompt → get_screenshot_file su FAIL → end_session. Una sessione per TC.

---

PATH WEB — Cypress + cypress-xray-plugin

Vedi reference/automation-channels.md#path-web per steps dettagliati (configurazione plugin, spec template, regole chiave Jira).

Sintesi: Crea TE Xray prima del run (Step 4.W0) → genera spec .cy.js con chiave Jira reale nel titolo it() → npx cypress run → sync automatico via plugin.

---

Fase 5 — Sync risultati e chiusura

Questa fase ha comportamento diverso per canale.

Path Mobile — raccolta risultati e aggiornamento TE:

La Test Execution per mobile va creata qui (dopo l'esecuzione), perché appium-mcp raccoglie i risultati passo per passo e li conosce solo a fine run.

Se la TE non esiste ancora (non trovata in Fase 1):

• Tier 1 (MCP): crea la TE e aggiorna ogni TC con stato PASS/FAIL e screenshot allegato
• Tier 3: mostra il report testuale completo e le istruzioni per aggiornare manualmente in Xray

Se la TE esiste già (trovata in Fase 1):

• Aggiungi i nuovi TC confermati e aggiorna gli stati. Non crearne una duplicata.

Path Web — verifica sync automatico:

La TE è già stata creata in Step 4.W0. Il sync risultati è automatico al termine di npx cypress run (gestito da cypress-xray-plugin). In questa fase verifichi solo che sia avvenuto correttamente.

Controlla nel log del run:

[cypress-xray-plugin] Test execution XE-456 updated successfully

Se il sync non è avvenuto: usa il fallback JUnit XML (vedi reference/cypress-xray-config.md).

Report finale:

🟡 MEDIO (reversibile) — 🔨 DevForge · siae-automation
🎫 Story: PROJ-XXX · 🧪 Test Exec: XE-456 [nuova / aggiornata] · 📱 Canale: Mobile Android / Web
✅ PASS: N TC · ❌ FAIL: N TC · ⏭️ SKIP: N TC · 🔄 Xray sync: Completato / CSV generato
▼ Azione
💡 Perche': Report finale esecuzione automation test
🚫 Se NO: Nessun report generato

---

Limiti Operativi

Vincolo	Limite	Se superato
Tentativi fix per errore	2	Fermati. Diagnosi diversa necessaria.
File modificati per singolo step	5	Se devi toccare piu' file, decomponi in sub-task.
Output max per raccomandazione	200 righe	Prioritizza. Top 5 issue, non lista esaustiva.

---

REQUIRED SUB-SKILL: siae-tdd

Implementa ogni test E2E seguendo il ciclo siae-tdd (test fallente, poi implementazione).

---

Tabella Anti-Razionalizzazione

Pensiero	Realta'
"Automatizza tutto con Automazione=Y, non serve valutare il ROI"	Automatizzare TC con 15 step o logica ambigua genera test fragili che si rompono a ogni release. Il ROI serve per scegliere cosa vale la manutenzione.
"La TL non esiste ancora, parto da zero"	Cerca sempre prima in Xray. Una TL potrebbe esistere da un sprint precedente o da un'altra sessione siae-qa. Non sovrascrivere lavoro fatto.
"Il developer non deve rivedere la lista, auto-approvo"	Il developer conosce la complessita' UI e i rischi di manutenzione. La proposta ROI e' un'ipotesi — la conferma e' obbligatoria.
"Genero i test per tutti i TC, poi il developer decide"	Generare test non selezionati e' spreco. La selezione avviene PRIMA della generazione.
"Il test E2E sostituisce il TC manuale in Xray"	No. Il test automatizzato aggiorna lo stato del TC manuale nella Test Execution. Il TC manuale resta — e' la fonte di verita'.
"Non serve la Test Execution di automation separata"	Serve. Mescolare risultati manuali e automatizzati nella stessa TE rende i report Xray illeggibili.
"Il test passa in locale, non serve BrowserStack"	BrowserStack esegue su device e browser reali. Un test che passa in locale puo' fallire su Android 12 Samsung o Safari iOS.
"Questo scenario lo testo a mano, e' piu' veloce che scrivere il test"	Un test manuale non si ripete. Un test E2E gira su ogni PR, ogni notte, su ogni ambiente. Il costo di scrittura si ammortizza al terzo run.
"Non ho tempo per automatizzare ora, lo faccio nel prossimo sprint"	Il debito di automation si accumula: piu' TC manuali si accumulano, piu' costoso e' recuperare. I bug di regressione trovati in produzione costano 10x di un test automatizzato scritto ora.
"Il sync con Xray e' opzionale, basta avere i test che passano"	Senza sync Xray i manager non vedono la copertura, le audit falliscono e i TC restano in stato 'Non eseguito' anche se il test verde gira in CI. La tracciabilita' Story→TC→Execution e' un requisito SIAE.
"Configuro la CI pipeline dopo il rilascio, ora ho fretta"	Una pipeline non configurata significa che i test E2E non proteggono main. Un bug introdotto passa inosservato fino al collaudo. Il gate CI e' la rete di sicurezza: va tesa prima, non dopo la caduta.
"I test E2E sono lenti, preferisco unit test"	Gli unit test non validano i flussi utente reali end-to-end. Un'app con 100% unit test puo' avere il login rotto in produzione. I due livelli sono complementari, non alternativi.
"Non sincronizo con Xray perche' la chiave Jira e' cambiata"	Aggiorna la mappatura nel titolo it() e riesegui. Non sincronizzare lascia la Test Execution con risultati obsoleti e invalida la reportistica di sprint.

---

CHECKLIST DI VERIFICA

• Canale rilevato (mobile/web)
• TL Xray esistente cercata prima di procedere
• Test Execution automation esistente verificata (non creare duplicati)
• ROI calcolato per ogni TC della TL
• Proposta automation presentata al developer con punteggio e ragionamento
• Lista confermata dal developer (con eventuali aggiunte o rimozioni)
• Test E2E generati solo per i TC nella lista confermata
• Test eseguiti (appium-mcp o npx cypress run)
• Screenshot allegati ai TC falliti
• Risultati sincronizzati in Xray TE o CSV prodotto per import manuale

---

Classificazione Rischio Operazioni

Operazione	Livello	Card
Setup framework E2E (Playwright/Cypress)	🟢 Sicuro	No
Scrittura test automatizzati	🟢 Sicuro	No
Esecuzione test E2E in locale	🟡 Medio	Si
Configurazione pipeline CI/CD	🟡 Medio	Si
Push configurazione CI su repository	🔴 Alto	Si
Abilitazione gate automatico su PR	🔴 Alto	Si

---

VINCOLI NON NEGOZIABILI

1. Cerca la TL esistente in Xray prima di qualsiasi altra operazione — non assumere che non esista
2. Non generare test senza lista confermata dal developer — la proposta ROI è un suggerimento, la scelta finale è del developer
3. La Test Execution automation è separata da quella manuale — non sovrascrivere risultati manuali
4. Nessun TC marcato PASS senza esecuzione effettiva — PASS = test eseguito e superato
5. Il titolo it() in Cypress deve usare la chiave Jira reale del TC (es. PROJ-456:) — il plugin non può fare il match con un ID sequenziale TC-{N}. Usa sempre la chiave dalla mappatura siae-qa.
6. BrowserStack App Automate per i risultati ufficiali Xray — non usare emulatori locali
7. Non modificare Automazione da Y a N se il test fallisce — un fallimento è un bug, non un cambio di scope

---

QUANDO SEI BLOCCATO

Problema	Soluzione
TL non trovata con JQL	Chiedi al developer la chiave del Test Plan o del Test Set Xray
appium-mcp non trova l'elemento	Chiedi al developer l'accessibility ID. Se non esiste, suggerisci di aggiungerlo al codice.
BrowserStack: errore upload artefatto	Verifica formato (APK signed, IPA con provisioning profile Ad Hoc/Enterprise)
cypress-xray-plugin non matcha il TC	Verifica che il titolo it() contenga la chiave Jira reale (es. PROJ-456:) e non TC-{N}:. Verifica anche che testExecutionIssueKey esista in Xray e non sia in stato chiuso.
Test Execution Xray non si aggiorna	Verifica XRAY_CLIENT_ID + XRAY_CLIENT_SECRET. Se scaduti, rigenera il token Xray Cloud.
TC ha ROI basso ma il developer vuole automatizzarlo	Segnala il rischio manutenzione, poi procedi — la decisione finale spetta al developer