Strumento di Analisi

Lo strumento analyze esegue un'analisi completa dell'accessibilità delle pagine web effettuando una scansione tramite l'Axe DevTools Browser Extension in un ambiente browser reale. Funziona perfettamente con URL di sviluppo locali (ad es., localhost:3000) e URL di produzione remoti.

Cosa fa

1. Autenticazione - Convalida le credenziali dell'utente (sia una chiave API che un token di accesso OAuth 2.0) per garantire l'accesso autorizzato
2. Recupero Configurazione - Recupera le impostazioni specifiche dell'organizzazione dell'utente Configurazione Axe, inclusi:
   • Standard di Test di Accessibilità (ad es., WCAG 2.2 AA)
   • versione di axe-core
   • Bisogna rivedere / migliori pratiche
   • preset Regole Avanzate
3. Analisi Basata su Browser - Avvia un'istanza del browser in background con l'estensione Axe DevTools montata
4. Navigazione tra le Pagine - Naviga all'URL fornito dall'utente nel loro prompt all'agente AI
5. Scansione di Accessibilità - Esegue un'analisi completa dell'accessibilità sulla pagina renderizzato utilizzando l'Axe DevTools Browser Extension, garantendo che venga testata la vera esperienza utente (non semplicemente l'HTML statico)
6. Consegna dei Risultati - Restituisce i risultati dell'analisi completa all'agente in un formato strutturato

Test di Responsività

Lo strumento analyze supporta parametri opzionali viewportWidth e viewportHeight, consentendo di testare le pagine a specifiche dimensioni del viewport. Questo è utile per individuare problemi di accessibilità che si manifestano solo a determinate dimensioni dello schermo, come punti di interruzione per dispositivi mobili o tablet.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Quando entrambi i parametri sono omessi, la scansione viene eseguita a 1000×1080. L'uso di viewportWidth da solo imposta l'altezza di default a 1080; viewportHeight richiede che viewportWidth sia impostato. Entrambe le dimensioni possono essere fino a 7680 pixel.

Scansioni di Pagine Parziali

Di default, lo strumento analyze esegue la scansione dell'intera pagina. Per limitare la scansione a una regione specifica, passa il parametro opzionale selector — utile per concentrarsi su un singolo componente o escludere parti della pagina rumorose e non pertinenti dai risultati.

• Una singola stringa selettore CSS mira a un elemento nel frame superiore:

  {
    "url": "http://localhost:3000",
    "selector": "#main"
  }

• Un array di selettori CSS attraversa i confini di iframe o shadow-DOM — ogni segmento seleziona il contenitore per il prossimo. Usa un array solo quando l'obiettivo risiede all'interno di un iframe o di una radice shadow:

  {
    "url": "http://localhost:3000",
    "selector": ["iframe#checkout", "#payment-form"]
  }

Un array supporta fino a 10 segmenti. Se il selettore non trova corrispondenza con alcun elemento sulla pagina, la scansione restituisce un errore. Quando selector è omesso, viene eseguita la scansione di tutta la pagina.

Chiedi al tuo agente AI in linguaggio naturale: l'agente traduce la tua intenzione nella chiamata dello strumento:

Scan only the #main region of http://localhost:3000 for accessibility issues

Interazioni con il Browser Prima della Scansione

Lo strumento analyze supporta un array opzionale before di passaggi interattivi che vengono eseguiti dopo il caricamento della pagina ma prima della scansione di accessibilità. Questo permette diversi scenari di test realistici:

• Pagine con login richiesto — compila le credenziali e inviale prima di scansionare la pagina post-login
• Bandiere dei cookie/consenso — elimina le bandiere che altrimenti coprirebbero o oscurerebbero il contenuto della pagina
• Contenuto dinamico — aspetta che il contenuto reso dal client (cambiamenti di percorso, DOM iniettati in ritardo) appaia prima di scansionare

I passaggi vengono eseguiti in ordine di array, nel stesso contesto del browser della scansione, così cookie, localStorage e eventuali cambiamenti di percorso innescati da click o fill persistono nella scansione.

L'array before supporta fino a 20 passaggi. Ogni passaggio ha il proprio timeout di BROWSER_TIMEOUT_MS (default 30000 ms); non c'è nessuna eccezione per ogni singolo passaggio.

Azioni Supportate

Esempio: accesso prima della scansione

Chiedi al tuo agente AI in linguaggio naturale: l'agente traduce la tua intenzione nella chiamata dello strumento:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

L'agente risolve il prompt e chiama lo strumento analyze con un payload simile a:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Iniezione di cookie

Lo strumento analyze supporta un array opzionale cookies che imposta i cookie sul contesto del browser prima della navigazione — così da farli viaggiare con la primissima richiesta alla pagina. Questo è distinto da azioni before, che viene eseguito dopo navigazione e quindi non può influenzare come viene indirizzata la richiesta iniziale. Due usi comuni:

• Instradamento ambientale — imposta un cookie di selezione per staging o feature-branch che un livello di edge o CDN legge per decidere quale versione del sito servire.
• Sessioni pre-autenticate — inietta un cookie di sessione valido così che la scansione inizi già autenticata, senza passare attraverso un modulo di login tramite before.

L'array cookies supporta fino a 20 cookie.

Campi dei cookie

Esempio: Arrivo su una pagina pre-autenticata

Chiedi al tuo agente AI in linguaggio naturale: l'agente traduce la tua intenzione nella chiamata dello strumento:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

L'agente risolve il valore del cookie e chiama lo strumento analyze con un payload simile a:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}

Screenshot

Lo strumento analyze può restituire uno screenshot della pagina insieme al report di violazione, così puoi vedere cosa è stato scansionato. Passa il parametro opzionale screenshot per aderire — un oggetto vuoto è sufficiente:

{
  "url": "http://localhost:3000",
  "screenshot": {}
}

PNG è il predefinito. Imposta format a "jpeg" per un'immagine più piccola su pagine con molte foto:

{
  "url": "http://localhost:3000",
  "screenshot": { "format": "jpeg" }
}

L'immagine viene restituita come un blocco di contenuti immagine MCP standard, dopo il report di violazione.

Cosa mostra lo screenshot

• Il viewport visibile, non l'intera pagina. Il contenuto al di sotto della piega non è incluso. Per catturare più della pagina, passa un viewportHeight alto (es. 4096) in modo che l'area visibile copra ciò che vuoi vedere.
• La pagina com'era immediatamente prima che la scansione iniziasse. La cattura avviene subito prima di axe.run(), quindi le modifiche al DOM che si verificano durante la scansione — rielaborazioni SPA, aggiornamenti useEffect, animazioni, richieste in corso — non sono riflessi. Nelle app a pagina singola questo disallineamento è comune.

Costo e supporto client

Il fatto che l'immagine venga resa inline dipende dal tuo client MCP. Il server restituisce sempre un blocco immagine valido per lo standard, ma alcuni client comprimono i risultati degli strumenti o omettono le anteprime delle immagini — VS Code con Copilot le visualizza, mentre Cursor e Claude Desktop potrebbero no. Una anteprima mancante è una limitazione della visualizzazione sul lato client, non un errore di acquisizione.

Salvataggio degli screenshot su disco

Lo screenshot può anche essere scritto su un file, che è il modo affidabile per vedere un'acquisizione in un client che non rende le immagini inline. Imposta saveTo a un percorso assoluto:

{
  "url": "http://localhost:3000",
  "screenshot": { "saveTo": "/Users/me/Desktop/home.png" }
}

Oppure imposta save: true per lasciare che il server scelga il nome del file:

{
  "url": "http://localhost:3000",
  "screenshot": { "save": true }
}

Il percorso assoluto che è stato scritto viene restituito nell'array messages della risposta, così il tuo agente può dirti dove trovare il file.

Il salvataggio si applica a solo scansioni riuscite. Se la scansione fallisce dopo che lo screenshot è stato catturato, l'immagine viene restituita in linea insieme all'errore indipendentemente da inline, e non viene mai scritta su disco.

Quando la cattura fallisce

La cattura dello screenshot è un tentativo al meglio delle possibilità e non causa mai il fallimento di una scansione. Se la cattura va in timeout, la scansione restituisce comunque i suoi risultati con una nota nell'array messages della risposta:

Screenshot capture failed: <reason>

Se la stessa scansione fallisce dopo che lo screenshot è stato scattato, l'immagine viene comunque restituita con la risposta di errore — lo stato visivo della pagina al momento del guasto è di solito la prova di debugging più utile che hai.

Regole Avanzate

Oltre al set di regole standard di axe-core, lo strumento analyze può eseguire Regole Avanzate — test automatici che utilizzano screenshot, visione artificiale e modelli linguistici di grandi dimensioni per individuare problemi che axe-core da solo non può rilevare, come intestazioni che sembrano intestazioni o immagini informative con testo alternativo poco utile.

Quale preset viene eseguito è governato dai Configurazione Axe della tua organizzazione e — dove il tuo amministratore lo consente — può essere sostituito per server con AXE_ADVANCED_RULES o per scansione con l'argomento advancedRules:

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough"
}

Ogni risposta riporta il preset che è stato effettivamente eseguito e da dove proviene:

{
  "advancedRules": {
    "value": "thorough",
    "source": "tool_arg"
  }
}

Le Regole Avanzate sono incluse nel tuo abbonamento Axe DevTools per Web — lo stesso che ti dà l'Axe MCP Server. Aggiungono circa 15-20 secondi a una scansione, consumano Crediti AI e sono l'unico caso in cui analyze invia dati della pagina (uno screenshot a pagina intera più la struttura della pagina) a Deque per la valutazione. Vedi Regole Avanzate per preset, precedenza, messaggi di degradazione e dettagli sulla privacy.

Benefici Chiave

• Test nel Browser Reale - Testa la pagina effettivamente renderizzata, non solo il codice sorgente, garantendo risultati accurati
• Standard Organizzativi - Rispetta le impostazioni di configurazione Axe del tuo team per test coerenti tra tutti gli utenti
• Copertura Completa - Sfrutta la piattaforma Axe all'avanguardia del settore
• Test di Responsività - Testa a dimensioni di viewport specifiche per rilevare problemi di accessibilità specifici per breakpoint
• Scansioni Mirate - Limita una scansione a una regione specifica, iframe o shadow root con il parametro selector
• Pagine Autenticate e Interattive - Scansiona pagine dietro un login, chiudi banner sui cookie, o attendi contenuti dinamici usando azioni before
• Cookie di Sessione e di Ambiente - Atterra già autenticato, o indirizza a un ambiente specifico, iniettando cookie prima della navigazione con il parametro cookies
• Contesto Visivo - Restituisci uno screenshot della pagina insieme al report con il parametro screenshot, anche quando una scansione fallisce
• Regole Avanzate - Scopri problemi che richiedono ragionamento visivo o contestuale, a una soglia di confidenza controllata dalla tua organizzazione
• Test Guidati Intelligenti - Esegui gli IGT (Keyboard, Interactive Elements, e Modal Dialog) sulla stessa pagina nella stessa chiamata con il parametro igtTools

Output

Lo strumento restituisce una risposta JSON strutturata che contiene:

• Tutte le violazioni di accessibilità trovate
• Livelli di gravità delle violazioni (critico, serio, moderato, minore)
• Selettori di elementi specifici e codice sorgente
• ID e descrizioni delle regole
• Un blocco advancedRules che riporta il preset Regole Avanzate che è stato eseguito e da dove proviene
• Un array messages che trasporta eventuali note sulla corsa (per esempio, una cattura dello screenshot fallita, una corsa di regole avanzate degradata, o il percorso a cui uno screenshot è stato salvato)

Quando screenshot è impostato, un blocco di contenuti dell'immagine segue il report. Quando igtTools è impostato, i risultati IGT sono restituiti insieme ai risultati Axe, indicizzati per nome IGT.