Test Guidati Intelligenti

Lo strumento analyze può eseguire gli Test Guidati Intelligenti Automatizzati (IGT) di Deque sulla pagina che esamina, nella stessa chiamata, subito dopo la scansione di Axe. Passa l'array opzionale igtTools che specifica quali IGT eseguire:

{
  "url": "http://localhost:3000",
  "igtTools": ["keyboard"]
}

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

Scan http://localhost:3000 for accessibility issues and run the keyboard IGT on it

Ogni IGT richiesto esegue in sequenza dopo la scansione Axe, nell'ordine in cui li elenchi, sulla stessa pagina, nello stesso browser, alla stessa larghezza del viewport. Qualsiasi cosa prepari la pagina viene eseguita una sola volta e si applica alla scansione e a ogni IGT: azioni before, iniezione di cookie e le parametri del viewport.

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

Forma della risposta

Impostando igtTools cambia la forma di data. Senza di esso, data è l'array delle problematiche Axe. Con esso, data ha due chiavi allo stesso livello, axe e igt, con una voce igt per ogni IGT richiesto:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "axe": [],
    "igt": {
      "keyboard": {
        "status": "complete",
        "issues": [],
        "igtElements": [],
        "terminatedReason": "keyboard-trap"
      },
      "modal": {
        "status": "complete",
        "issues": [],
        "igtElements": []
      }
    }
  }
}

• status — "complete" o "error". Controllalo prima di leggere qualsiasi altra cosa: issues e igtElements sono presenti solo su "complete", e error solo su "error". Selezione Fase aggiunge tre stati in più per l'IGT degli Elementi Interattivi.
• issues — i problemi di accessibilità che l'IGT ha trovato. Il conteggio dei problemi è la lunghezza di questo array.
• igtElements — ogni elemento che l'IGT ha processato, non solo quelli con problemi. Le voci con analysisFailed: true non sono state analizzate dall'AI e dovrebbero essere riviste manualmente. Ogni voce è limitata solo ai campi identificativi: vnodeId, selector, tagName, role, accessibleName, states e analysisFailed, presenti solo quando l'elemento lo contiene.
• terminatedReason — presente solo quando l'esecuzione si è conclusa prima che ogni passaggio fosse terminato, quindi i risultati potrebbero essere parziali. Non è un errore. Vedi Motivi di Terminazione.

Motivi di Terminazione

L'IGT degli Elementi Interattivi non ha motivi di terminazione propri. Una pagina senza elementi interattivi restituisce un risultato "complete" con array vuoti.

I guasti sono isolati

An IGT that fails does non fail the call and never affects the Axe results or the other IGTs. The failure is reported as that IGT's own status: "error" with a message. The Axe results and every other IGT's results come back normally. This includes when your organization's machine learning setting is disabled, in which case each IGT's entry explains that machine learning is required.

Uso dei crediti

Gli IGT sono potenziati dall'AI e fanno parte del AI Credit Management System. Ogni esecuzione consuma crediti AI dalla allocazione mensile della tua organizzazione; la scansione Axe di per sé no. Richiedi gli IGT in modo mirato piuttosto che aggiungerli a ogni scansione. Per l'Interactive Elements IGT, il scoping o il scegliere gli elementi riduce il numero di elementi analizzati e quindi i crediti utilizzati.

IGT degli Elementi Interattivi

L'Interactive Elements IGT trova i pulsanti, i link e i controlli personalizzati sulla pagina e utilizza l'AI per controllare il nome accessibile, il ruolo e lo stato di ciascuno. Per default, analizza ogni elemento interattivo trovato in una singola chiamata:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"]
}

Analyze http://localhost:3000 and run the interactive elements guided test

Ogni elemento analizzato consuma crediti AI, quindi su una pagina grande — una griglia di dati, un lungo menu di navigazione, un elenco di prodotti — l'esecuzione di default può consumare molti. Due opzioni limitano cosa viene analizzato.

Limitazione con includeSelectors

Passa includeSelectors, un array di selettori CSS, per analizzare solo gli elementi che corrispondono. Gli elementi al di fuori dei selettori non sono analizzati:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "includeSelectors": ["#main", "nav.primary"]
}

Analyze http://localhost:3000 and run the interactive elements guided test,
but only on the elements inside #main and nav.primary

includeSelectors è diverso dal analyze's selector. selector limita quale parte della pagina il scansione Axe copre, mentre includeSelectors limita quali elementi il IGT degli Elementi Interattivi analizza. Puoi usare uno dei due, o entrambi. includeSelectors richiede "interactive-elements" nel igtTools.

Scelta degli elementi da testare

Quando non sai in anticipo quali elementi sono importanti, usa selezione graduale. Divide il test in due chiamate di strumenti, con una pausa in mezzo per scegliere cosa viene analizzato:

1. Prima chiamata — trova elementi. L'agente chiama analyze con interactive: true. La scansione Axe si esegue normalmente, e l'IGT trova gli elementi interattivi della pagina ma non esegue nessuna analisi AI su di essi. L'esecuzione si mette in pausa e restituisce l'elenco degli elementi trovati, più un sessionID.
2. Tu scegli. L'agente ti mostra l'elenco — il ruolo di ogni elemento, il nome accessibile e lo stato, raggruppato per componente o ruolo dove possibile — e tu indichi quali testare.
3. Seconda chiamata — analizza. L'agente chiama ancora analyze con sessionID e i selectedIDs che hai scelto. L'esecuzione in pausa continua nella stessa sessione del browser, senza ricaricare la pagina o trovare nuovamente gli elementi, e restituisce un normale risultato "complete" solo per gli elementi selezionati.

Un prompt che lo richiede:

Analyze http://localhost:3000 and run the interactive elements guided test.
Show me the interactive elements it finds first and let me choose which
ones to test.

La prima chiamata:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "interactive": true
}

restituisce i risultati di Axe e i candidati:

{
  "pageUrl": "http://localhost:3000",
  "data": {
    "axe": [],
    "igt": {
      "interactive-elements": {
        "status": "needs_selection",
        "sessionID": "3f9c…",
        "candidates": [
          { "vnodeId": 12, "role": "button", "name": "Add to cart" },
          { "vnodeId": 31, "role": "link", "name": "Checkout" }
        ],
        "componentGroups": { "intelligent": [], "role": [] }
      }
    }
  }
}

La seconda chiamata nomina i candidati scelti per vnodeId:

{
  "url": "http://localhost:3000",
  "igtTools": ["interactive-elements"],
  "sessionID": "3f9c…",
  "selectedIDs": [12]
}

Tieni presente quanto segue quando usi la selezione graduale:

• Esegue solo l'Interactive Elements IGT. igtTools devono essere esattamente ["interactive-elements"] in entrambe le chiamate. Per eseguire anche i Keyboard o i Modal IGT, eseguili in una chiamata separata.
• La seconda chiamata omette data.axe. I risultati di Axe sono arrivati nella prima chiamata. Nella seconda chiamata, tutti i parametri di configurazione (viewportWidth, viewportHeight, cookies, before, selector, advancedRules, screenshot, chromePath) sono ignorati perché la sessione del browser in pausa viene riutilizzata così com'è. url è ancora richiesto.
• includeSelectors si applica ancora. Passalo alla prima chiamata per limitare quali elementi appaiono nell'elenco.
• selectedIDs deve provenire dall'elenco. Se un ID non era nei candidati, la chiamata restituisce status: "invalid_selection" con gli ID sconosciuti in unknownIDs. L'esecuzione rimane in pausa, quindi l'agente può riprovare con ID validi.
• Le esecuzioni in pausa scadono. Un'esecuzione che non viene continuata entro 3 minuti viene chiusa e restituisce status: "session_expired". Al massimo 3 esecuzioni in pausa possono essere aperte contemporaneamente. Entrambi i limiti sono configurabili con SELECTION_SESSION_TTL_MS e MAX_SELECTION_SESSIONS. Dopo una scadenza, avvia una nuova chiamata interactive: true.

IGT del Dialogo Modale

Il test del dialogo modale IGT esamina un singolo dialogo modale sulla pagina. Controlla che il focus della tastiera rimanga all'interno del modale mentre è aperto e che il modale abbia le corrette semantiche di dialogo (aria-modal e il ruolo del contenitore modale). Quando il test ha l'elemento che apre il modale, controlla anche che il modale può essere chiuso e che il focus ritorna a un posto sensato in seguito.

Il test deve sapere quale modale controllare. Ci sono tre modi per indicarlo:

Usa modalTriggerSelector ogni volta che il modale ha un trigger — è l'unica modalità che controlla tutto. Il test clicca sul trigger stesso:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalTriggerSelector": "#open-dialog"
}

Analyze http://localhost:3000 and run the modal guided test on the dialog
opened by #open-dialog

Usa modalSelector quando non c'è trigger da cliccare, come un modale che si apre quando la pagina viene caricata. Se il modale appare solo dopo un'interazione, usa before per aprirlo prima:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalSelector": "#newsletter-dialog"
}

Senza alcun selettore, il test controlla qualunque modale sia aperto una volta che i passaggi before vengono completati. Usa questo per modali che nessun singolo elemento apre, come uno che appare dopo una sequenza di tasti o un timeout di sessione:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "before": [
    { "action": "click", "selector": "#settings" },
    { "action": "click", "selector": "#delete-account" }
  ]
}

Entrambi i selettori accettano una stringa CSS per un elemento nel frame superiore, o un array di selettori per raggiungere un elemento all'interno di un iframe (per esempio, ["iframe#app", "#open-dialog"]), lo stesso formato di selector.

Fornire un selettore modale di fallback

Se conosci sia il trigger che l'elemento modale, passa entrambi. Il test parte comunque dal trigger e continua a controllare tutto. Il modalSelector viene utilizzato solo se il test non riesce a identificare il modale dopo aver cliccato sul trigger — tipicamente perché il modale utilizza un markup non standard:

{
  "url": "http://localhost:3000",
  "igtTools": ["modal"],
  "modalTriggerSelector": "#open-dialog",
  "modalSelector": "#custom-dialog"
}

Il risultato non indica se è stato usato il fallback. Un'esecuzione che ne ha bisogno ha controllato un elemento che il test non poteva riconoscere come un modale, quindi tratta una lista issues vuota da un'esecuzione con entrambi i selettori come evidenza più debole rispetto a una da un'esecuzione solo trigger.

Non aprire il modale da solo

Quando passi modalTriggerSelector, il test clicca sul trigger per aprire il modale. Se il modale è già aperto, quel clic solitamente lo chiude di nuovo. Quindi:

• Non cliccare sul trigger in before. Un clic before sullo stesso selettore di modalTriggerSelector viene rifiutato con un errore. Usa before per raggiungere lo stato della pagina in cui vive il trigger, come effettuare il login o andare a una vista particolare.
• Non passare un trigger per un modale che è già aperto, sia al caricamento della pagina che da un passaggio before. Usa modalSelector da solo invece.

modalTriggerSelector e modalSelector richiedono entrambi "modal" in igtTools.

Esecuzione di tutto in una sola chiamata

Ogni IGT ha le sue opzioni, quindi una chiamata analyze può eseguire la scansione Axe, Regole avanzate e ogni IGT sulla stessa pagina. La pagina viene caricata e preparata una volta, e ogni risultato ritorna sotto la sua chiave.

Analyze http://localhost:3000 for accessibility issues with thorough
advanced rules. Also run the keyboard, interactive elements, and modal
guided tests (test the modal triggered by button#open-dialog).

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

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough",
  "igtTools": ["keyboard", "interactive-elements", "modal"],
  "modalTriggerSelector": "button#open-dialog"
}

e riceve i risultati Axe (comprese le scoperte delle Regole Avanzate) sotto data.axe e una voce per IGT sotto data.igt:

{
  "pageUrl": "http://localhost:3000",
  "advancedRules": { "value": "thorough", "source": "tool_arg" },
  "data": {
    "axe": [],
    "igt": {
      "keyboard": { "status": "complete", "issues": [], "igtElements": [] },
      "interactive-elements": {
        "status": "complete",
        "issues": [],
        "igtElements": []
      },
      "modal": { "status": "complete", "issues": [], "igtElements": [] }
    }
  }
}

Gli IGT vengono eseguiti uno dopo l'altro, nell'ordine elencato in igtTools, e ciascuno riporta separatamente — una trappola da tastiera o un modale che non può essere trovato non ferma gli altri. Questo funziona anche con ogni altra opzione analyze: passaggi before e cookies per una pagina protetta da login, viewportWidth per un breakpoint mobile, selector per delimitare la scansione Axe e screenshot.

Lo strumento igt

Lo strumento igt esegue i Test Guidati Intelligenti Automatici di Deque su una pagina web come una chiamata standalone. Tutto ciò che fa, analyze lo fa ora nella stessa chiamata della scansione di accessibilità — vedi il resto di questa pagina per l'uso e il consumo di crediti, che sono gli stessi per entrambi.

L'oggetto risultato per test è anche lo stesso per entrambi — status, issues, igtElements e un eventuale terminatedReason, come descritto in Forma della risposta. Solo la busta differisce: igt restituisce i suoi risultati direttamente sotto data, indicizzati per nome del test (data.keyboard), mentre analyze li annida sotto data.igt insieme a data.axe.