--- name: "dev-gherkin-help" description: "Cheatsheet interattivo Gherkin italiano per MUCC. Mostra 5 esempi canonici Gherkin `# language: it` con spiegazione inline, tabella keyword IT/EN, anti-pattern da evitare e verifica presenza file .feature nel progetto corrente. Usa quando vuoi 'esempi Gherkin', 'come si scrive un AC in Gherkin', 'cheatsheet keyword italiane', 'anti-pattern Gherkin', 'verificare feature files', 'imparare Gherkin in italiano'. Progettato per chi incontra Gherkin per la prima volta in MUCC: bastano 5 minuti per scrivere il primo scenario corretto." --- # /dev-gherkin-help — Gherkin Italiano: Cheatsheet + Esempi Canonici (v0.17.0+) Skill di consultazione rapida per la sintassi Gherkin italiana (`# language: it`) adottata da MUCC come standard AC a partire da v0.17.0. Non richiede installazione di tool aggiuntivi: la skill legge i file del progetto e risponde inline. --- ## Modalità | Flag | Comportamento | |------|---------------| | _(default, nessun flag)_ | Mostra i 5 esempi canonici con label e spiegazione inline | | `--cheatsheet` | Tabella keyword italiane con equivalente inglese Cucumber ufficiale | | `--anti-patterns` | 5+ anti-pattern con coppia ❌ prima / ✅ dopo e spiegazione | | `--check-project` | Verifica presenza file `.feature` in `specs/features/` del progetto corrente | | `--all` | Mostra tutto: esempi + cheatsheet + anti-pattern | --- ## Workflow operativo ### Modalità default (5 esempi canonici) Quando invocata senza flag, la skill produce i 5 esempi canonici nella sequenza ordinata. Ogni esempio è preceduto da una label `✅ Esempio N — [tipo]` seguita da una spiegazione inline di 2-3 righe che spiega **perché** quella struttura è corretta, poi il blocco ```gherkin```. #### ✅ Esempio 1 — Happy path con `Scenario` La struttura base di Gherkin: un singolo scenario con pre-condizione (`Dato`), azione utente (`Quando`), risultato atteso (`Allora`). Il tag `@AC-NNN` è obbligatorio per il mapping su `test-map.md`. Ogni step su una riga, nessuna congiunzione nella stessa riga. ```gherkin # language: it Funzionalità: Autenticazione utente Come utente registrato Voglio effettuare il login Per accedere alla mia area personale @AC-001 @happy-path Scenario: Login con credenziali valide Dato che l'utente si trova sulla pagina di login Quando inserisce email "mario@example.com" e password "secret123" E clicca su "Accedi" Allora viene reindirizzato alla dashboard E vede il messaggio "Benvenuto, Mario" ``` #### ✅ Esempio 2 — Error path con `Scenario` Un error path testa il comportamento del sistema di fronte a input non validi o situazioni di errore. Il tag `@error-path` documenta l'intenzione. Il messaggio di errore specifico nell'`Allora` rende il test deterministico. ```gherkin # language: it Funzionalità: Autenticazione utente @AC-002 @error-path Scenario: Login con password errata Dato che l'utente si trova sulla pagina di login Quando inserisce email "mario@example.com" e password "sbagliata" E clicca su "Accedi" Allora viene mostrato il messaggio di errore "Credenziali non valide" E rimane sulla pagina di login Ma il campo password è svuotato ``` #### ✅ Esempio 3 — Edge case con `Contesto` Il `Contesto:` (Background in inglese) esegue step condivisi prima di ogni scenario nel file. Utile per ridurre duplicazione quando tutti gli scenari partono dallo stesso stato. L'edge case testa comportamenti limite: stringa vuota, campo nullo, lunghezza massima. ```gherkin # language: it Funzionalità: Validazione form registrazione Contesto: Dato che il sistema di registrazione è disponibile E il database utenti è raggiungibile @AC-003 @edge-case Scenario: Registrazione con email già esistente Dato che esiste già un account con email "mario@example.com" Quando un nuovo utente prova a registrarsi con la stessa email Allora il sistema mostra "Questa email è già registrata" E suggerisce il link "Hai dimenticato la password?" Ma non crea un duplicato nel database ``` #### ✅ Esempio 4 — Data-driven con `Schema dello scenario` + `Esempi:` `Schema dello scenario:` (Scenario Outline) permette di eseguire lo stesso scenario con dati diversi. I placeholder `` vengono sostituiti dalle colonne della tabella `Esempi:`. Riduce drasticamente la duplicazione per test con input multipli. ```gherkin # language: it Funzionalità: Calcolo sconto ordine @AC-004 @happy-path Schema dello scenario: Sconto applicato correttamente per fascia importo Dato che il carrello ha un totale di euro Quando il sistema calcola lo sconto Allora lo sconto applicato è % E il totale finale è euro Esempi: | importo | sconto_percentuale | totale_scontato | | 50 | 0 | 50 | | 100 | 5 | 95 | | 200 | 10 | 180 | | 500 | 15 | 425 | ``` #### ✅ Esempio 5 — Security/Performance con tag `@security` / `@performance` I tag `@security` e `@performance` permettono di filtrare l'esecuzione (`cucumber --tags @security`). Gli scenari di sicurezza testano tentativi di attacco; quelli di performance usano soglie temporali misurabili. Entrambi richiedono step precisi e quantificati. ```gherkin # language: it Funzionalità: Protezione endpoint API @AC-005 @security Scenario: Tentativo di SQL injection nel campo ricerca Dato che un attaccante ha un token di sessione valido Quando invia una richiesta GET /api/prodotti?q=' OR 1=1 -- Allora il server risponde con HTTP 400 E il corpo della risposta non contiene dati di database Ma il tentativo viene registrato nel log di sicurezza @AC-006 @performance Scenario: Tempo di risposta login sotto soglia Dato che il sistema ha 10.000 utenti registrati Quando un utente effettua il login con credenziali valide Allora la risposta arriva entro 500 millisecondi E il token JWT è presente nell'header Authorization ``` --- ### Modalità `--cheatsheet` Quando invocata con `--cheatsheet`, la skill produce la tabella completa delle keyword Gherkin italiane (`# language: it`) con equivalente inglese ufficiale Cucumber e note d'uso. #### Keyword principali | Keyword italiana | Equivalente inglese | Uso | |-----------------|---------------------|-----| | `Funzionalità:` | `Feature:` | Titolo del file — descrive la funzionalità testata | | `Contesto:` | `Background:` | Step condivisi eseguiti prima di ogni scenario nel file | | `Scenario:` | `Scenario:` | Singolo caso di test con esempio concreto | | `Schema dello scenario:` | `Scenario Outline:` | Scenario parametrico da ripetere con dati diversi | | `Scenario schema:` | `Scenario Outline:` | Alias alternativo accettato da Cucumber | | `Esempi:` | `Examples:` | Tabella dati per `Schema dello scenario:` | #### Step keyword | Keyword italiana | Equivalente inglese | Uso | |-----------------|---------------------|-----| | `Dato` | `Given` | Pre-condizione / stato iniziale del sistema | | `Data` | `Given` | Variante femminile di `Dato` | | `Dati` | `Given` | Variante plurale di `Dato` | | `Date` | `Given` | Variante femminile plurale di `Dato` | | `Quando` | `When` | Azione dell'utente o evento che si verifica | | `Allora` | `Then` | Risultato atteso / asserzione verificabile | | `E` | `And` | Continua lo step precedente dello stesso tipo | | `Ma` | `But` | Contrasto rispetto allo step precedente (negazione) | #### Tag convenzionali MUCC | Tag | Scopo | |-----|-------| | `@AC-NNN` | Mapping obbligatorio su `test-map.md` (es. `@AC-001`) | | `@happy-path` | Scenario di percorso nominale (funziona tutto) | | `@error-path` | Scenario di gestione errori e input non validi | | `@edge-case` | Caso limite o comportamento ai confini del dominio | | `@security` | Test di sicurezza (injection, authn/authz, OWASP) | | `@performance` | Test con soglie temporali misurabili | | `@smoke` | Test di fumo: verifica rapida che il sistema sia up | #### Convenzioni file MUCC - Ogni `.feature` inizia con `# language: it` come prima riga - File nella directory `specs/features/` del progetto - Dimensione file: ≤ 80 righe - Scenari per file: ≤ 7 scenari - Ogni scenario ha almeno un tag `@AC-NNN` - Nomenclatura: `{story-id}-{nome-funzionalita}.feature` (es. `us-007-login.feature`) --- ### Modalità `--anti-patterns` Quando invocata con `--anti-patterns`, la skill produce almeno 5 anti-pattern con coppia ❌ (esempio sbagliato) e ✅ (esempio corretto) e spiegazione del perché. #### Anti-pattern 1 — Step multipli congiunti in una riga ❌ **Problema**: unire più azioni o condizioni con "e" nella stessa riga rende il test ambiguo e difficile da debuggare quando fallisce. ```gherkin # ❌ SBAGLIATO: tre condizioni in un solo step Dato che l'utente è loggato e la sessione è valida e il token non è scaduto ``` ✅ **Corretto**: ogni condizione su uno step separato — quando il test fallisce si sa esattamente quale condizione è rotta. ```gherkin # ✅ CORRETTO: condizioni separate Dato che l'utente è loggato E la sessione è valida E il token non è scaduto ``` #### Anti-pattern 2 — Dettagli implementativi nello step ❌ **Problema**: riferire database, query SQL, ID tecnici o strutture interne rende il test fragile rispetto ai refactoring interni. ```gherkin # ❌ SBAGLIATO: dettaglio tecnico esposto Dato che il record con id=42 nella tabella users ha status=1 nel database PostgreSQL ``` ✅ **Corretto**: descrivere lo stato di business, non l'implementazione. Il test sopravvive a un cambio di DB. ```gherkin # ✅ CORRETTO: stato di business Dato che l'utente "Mario Rossi" ha un account attivo ``` #### Anti-pattern 3 — Step `Quando` con più azioni ❌ **Problema**: il `Quando` dovrebbe essere una sola azione utente. Più azioni rendono il test non atomico. ```gherkin # ❌ SBAGLIATO: due azioni in un When Quando inserisce l'email, clicca su avanti e poi inserisce la password ``` ✅ **Corretto**: un `Quando` principale, azioni aggiuntive con `E`. ```gherkin # ✅ CORRETTO: azione principale + step secondari Quando inserisce l'email "mario@example.com" E clicca su "Avanti" E inserisce la password "secret123" ``` #### Anti-pattern 4 — `Allora` senza asserzione verificabile ❌ **Problema**: un'asserzione vaga non è verificabile automaticamente. "funziona correttamente" non ha significato misurabile. ```gherkin # ❌ SBAGLIATO: asserzione vaga Allora il login funziona correttamente ``` ✅ **Corretto**: asserzione specifica con risultato osservabile (URL, messaggio, stato UI). ```gherkin # ✅ CORRETTO: asserzione osservabile Allora viene reindirizzato a /dashboard E vede il titolo "La mia area personale" ``` #### Anti-pattern 5 — Scenario senza tag `@AC-NNN` ❌ **Problema**: senza il tag `@AC-NNN`, lo scenario non può essere mappato su `test-map.md` e la copertura AC non è tracciabile da `validate-spec-standards.ts`. ```gherkin # ❌ SBAGLIATO: nessun tag AC Scenario: Login con credenziali valide Dato che ... ``` ✅ **Corretto**: ogni scenario ha almeno il tag `@AC-NNN` corrispondente all'acceptance criterion che verifica. ```gherkin # ✅ CORRETTO: tag obbligatorio presente @AC-001 @happy-path Scenario: Login con credenziali valide Dato che ... ``` #### Anti-pattern 6 — File `.feature` oltre 80 righe o oltre 7 scenari ❌ **Problema**: file grandi sono difficili da revisionare, rallentano il parser e mescolano concern diversi. ```gherkin # ❌ SBAGLIATO: 15 scenari in un file, 200 righe Funzionalità: Gestione utenti Scenario: Login ... Scenario: Logout ... Scenario: Registrazione ... Scenario: Reset password ... ... (altri 11 scenari) ``` ✅ **Corretto**: split per funzionalità, un file per area logica, ≤7 scenari per file. ```gherkin # ✅ CORRETTO: file separati per area # us-001-login.feature (3 scenari: happy path + 2 error) # us-002-registrazione.feature (4 scenari: happy + 3 edge case) # us-003-reset-password.feature (2 scenari) ``` --- ### Modalità `--check-project` Quando invocata con `--check-project`, la skill cerca file `.feature` in `specs/features/` usando `Glob` o `find`. **Step 1**: verifica che la directory `specs/features/` esista nel working directory corrente. **Step 2**: se la directory non esiste o non contiene file `.feature`: ``` Nessun file .feature trovato in specs/features/ — il primo si crea con /dev-stories ``` **Step 3**: se esistono file `.feature`, la skill elenca i file trovati con il conteggio degli scenari per file e verifica che ogni scenario abbia almeno un tag `@AC-NNN`. Per ogni file con scenari senza tag segnala: ``` ⚠️ {nome-file}.feature — Scenario "{titolo}" manca tag @AC-NNN Soluzione: aggiungi @AC-NNN prima di Scenario (vedi /dev-gherkin-help --cheatsheet) ``` **Step 4**: se tutti gli scenari hanno il tag, output: ``` ✅ {N} file .feature trovati in specs/features/ — tutti gli scenari hanno @AC-NNN ``` --- ## Riferimenti interni - `dev-methodology/skills/dev-stories/SKILL.md` — come generare `.feature` da user stories - `dev-methodology/skills/dev-validate-specs/SKILL.md` — validatore che verifica `@AC-NNN` nei `.feature` - `specs/v0.17-spec-standards/testing/cheatsheet-gherkin-italiano.md` — reference standalone - Documentazione ufficiale Cucumber: [cucumber.io/docs/gherkin/languages](https://cucumber.io/docs/gherkin/languages/) (keyword `it`) --- ## Quando viene invocata ### Trigger espliciti dall'utente - "Mostrami esempi Gherkin italiano" - "Come si scrive uno scenario in italiano?" - "Cheatsheet keyword Gherkin" - "Esempi di Scenario schema con Esempi:" - "Anti-pattern Gherkin da evitare" - "Verifica i file .feature del progetto" ### Trigger automatici da altre skill | Skill chiamante | Step | Scopo | |-----------------|------|-------| | `/dev-stories` | Post-generazione AC | Suggerisce `/dev-gherkin-help` se il progetto usa Gherkin per la prima volta | | `migrate-specs-v1-to-v2.ts` | `manual-needed` per AC prosa | Suggerisce `/dev-gherkin-help` come guida per conversione manuale | | `/dev-validate-specs` | Warning `GHERKIN_MISSING_AC_TAG` | Link a `/dev-gherkin-help --cheatsheet` come rimedio |