Pa11y

Definizione — Pa11y è una suite open-source per l’analisi automatica dell’accessibilità. Fornisce: pa11y (CLI) per audit su singoli URL o viste autenticante, pa11y-ci per l’integrazione in CI/CD e Pa11y Dashboard per monitorare più pagine nel tempo. Rileva problemi riconducibili ai criteri WCAG 2.x (es. nomi accessibili, ruoli, etichette, contrasti, struttura).

Quando usarlo

• In sviluppo: check veloce mentre si lavora su componenti o template.
• In CI/CD: “quality gate” che fallisce la build se compaiono violazioni oltre la soglia.
• In monitoraggio: Dashboard pianifica scan periodici e segnala regressioni.

Esecuzione base (CLI)

# Analizza una pagina con standard WCAG 2.1 AA
npx pa11y https://example.com --standard WCAG2AA --reporter cli

# Output JSON (per consumo in script)
npx pa11y https://example.com --standard WCAG2AA --reporter json > report.json

# Attendi caricamenti dinamici
npx pa11y https://app.example.com --wait 1000

pa11y-ci (pipeline)

{
  "defaults": {
    "standard": "WCAG2AA",
    "wait": 800,
    "timeout": 60000
  },
  "urls": [
    "https://example.com/",
    "https://example.com/servizi/",
    { "url": "https://example.com/login", "actions": ["set field #email test@example.com", "set field #pwd P@ssw0rd", "click button[type=submit]", "wait 1000"] }
  ],
  "threshold": 0  // fallisce se >0 errori
}

Dashboard (monitoraggio)

• Raccoglie risultati nel tempo, utile per verificare regressioni dopo rilasci.
• Consente liste di URL, autenticazione e pianificazione (cron) degli audit.

Consigli pratici

• Coverage: scegli un campione rappresentativo (home, listing, dettaglio, form, modali, flussi critici).
• Soglie: fallisci su “error” e registra “warning” come debito tecnico con priorità.
• Insieme ad altri tool: affianca axe-core e Lighthouse per massimizzare copertura.
• Controlli manuali: verifica ordine di focus, gestione modali, testi alternativi “di senso”, test con screen reader.

Limiti

• Automazione ≠ conformità: gli strumenti automatici intercettano solo una parte delle violazioni; serve sempre un audit manuale.
• Falsi positivi/negativi: dipendono da markup, stati dinamici e timing; usa --wait e azioni per riprodurre correttamente la UI.

Esempio GitHub Actions (principio)

name: a11y-ci
on: [push, pull_request]
jobs:
  pa11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx pa11y-ci