Utilizzare i selettori dinamici

Quando si testano pagine che generano ID di elementi o nomi di classe dinamici a ogni caricamento della pagina, Axe Watcher potrebbe avere difficoltà a stabilire se i problemi di accessibilità siano duplicati tra le esecuzioni del test. Questo articolo spiega come configurare Watcher per gestire correttamente questi scenari. Un URL dinamico provoca lo stesso sintomo per una ragione diversa e necessita di una correzione diversa, trattata URL dinamici di seguito.

Il problema con i selettori dinamici

Per impostazione predefinita, Axe Watcher utilizza i selettori CSS che includono ID di elementi e classi per identificare dove si verificano problemi di accessibilità. Ad esempio, un problema potrebbe essere segnalato in:

iframe#main-iframe

Questo approccio funziona bene quando gli ID e le classi della tua pagina rimangono consistenti tra i caricamenti della pagina. Tuttavia, molte applicazioni web moderne generano identificatori dinamici che cambiano a ogni rendering della pagina, come:

• #component-a1b2c3d4
• .form-field-xyz789

Axe Watcher invia inoltre un XPath per ogni elemento, e Axe Developer Hub considera una corrispondenza su ciascun selettore come lo stesso elemento. Poiché un XPath non include mai i nomi delle classi, una pagina i cui nomi delle classi sono dinamici viene spesso tracciata correttamente senza ulteriori configurazioni. Tuttavia, un XPath include l'ID di un elemento quando quell'ID è unico sulla pagina, producendo un percorso come //div[@id='component-a1b2c3d4']. Un ID dinamico quindi modifica il selettore CSS e l'XPath insieme, lasciando nulla di stabile su cui basarsi.

Quando gli identificatori cambiano tra le esecuzioni dei test in questo modo, Axe Watcher non può determinare se un problema sia un duplicato di un problema già rilevato o una nuova occorrenza. Questo può portare a:

• Lo stesso problema segnalato come "nuovo" e "risolto" a ogni esecuzione del test
• Monitoraggio inaccurato del progresso dell'accessibilità nel tempo
• Difficoltà nell'identificare quali problemi sono stati effettivamente risolti

La soluzione: Abilitare il tracciamento delle genealogie

Per gestire i selettori dinamici, imposta l'opzione ancestry su true nella tua configurazione runOptions. Quando abilitato, Axe Watcher utilizza la posizione dell'elemento all'interno dell'albero DOM piuttosto che fare affidamento su ID e classi per individuare gli elementi tra le esecuzioni dei test.

Con ancestry abilitato, un selettore che in precedenza appariva così:

iframe#main-iframe

Includerà invece il percorso completo dall'elemento radice:

html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

Questo selettore posizionale rimane coerente tra i caricamenti delle pagine, anche quando gli ID e le classi cambiano, permettendo ad Axe Watcher di monitorare accuratamente i problemi duplicati.

Esempi di configurazione

JavaScript e TypeScript

Aggiungi l'opzione ancestry alla runOptions della tua configurazione axe:

const config = {
  axe: {
    apiKey: process.env.ACCESSIBILITY_API_KEY,
    projectId: process.env.PROJECT_ID,
    runOptions: {
      ancestry: true
    }
  }
}

Java

Utilizza il metodo setAncestry() sul tuo oggetto AxeRunOptions:

AxeRunOptions runOptions = new AxeRunOptions()
    .setAncestry(true);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setRunOptions(runOptions);

AxeWatcher watcher = new AxeWatcher(options);

Quando utilizzare il tracciamento delle genealogie

Abilita ancestry: true quando la tua applicazione:

• Usa framework che generano ID di componenti dinamici (React, Vue, Angular)
• Implica librerie CSS-in-JS che generano nomi di classi unici
• Ha campi modulo o elementi interattivi con identificatori generati automaticamente
• Mostra conteggi incoerenti di "nuovo problema" e "problema risolto" tra le esecuzioni dei test per quelli che sembrano gli stessi problemi

Compromessi da considerare

Sebbene il tracciamento delle genealogie risolva il problema dei selettori dinamici, ci sono alcune considerazioni:

• Leggibilità del selettore: I selettori posizionali sono più lunghi e possono essere più difficili da leggere quando si recensiscono problemi nell'Axe Developer Hub.
• Sensibilità alla struttura del DOM: Se la struttura del DOM della tua pagina cambia significativamente tra i rendering (non solo gli ID/classi), anche i selettori posizionali possono cambiare.
• Debug: Quando indaghi su un problema, potresti trovare più facile individuare un elemento tramite un ID significativo piuttosto che tramite la sua posizione nell'albero DOM.

Per la maggior parte delle applicazioni con identificatori dinamici, i vantaggi di un monitoraggio accurato dei problemi superano questi compromessi.

URL dinamici

I selettori di elementi sono solo una parte di come Axe Developer Hub identifica un problema. Viene confrontato anche l'URL della pagina, nella sua interezza, inclusa qualsiasi stringa di query. Abilitare ancestry non ha alcun effetto su questo confronto.

Un URL che varia tra le esecuzioni del test produce quindi gli stessi sintomi di un selettore dinamico, e lo fa in modo più aggressivo: quando un URL non è stato mai visto prima, ogni problema riscontrato viene segnalato come nuovo, senza consultare affatto i selettori di elementi. Cause comuni includono:

• ID di sessione o token di autenticazione trasportati nella stringa di query
• Timestamp o parametri per eludere la cache, come ?v=1738012800
• ID randomizzati nel percorso, come /orders/8f3c1b2a/summary
• Fixture di test che generano un nuovo record, e quindi un nuovo URL, a ogni esecuzione

Non esiste un'opzione di configurazione che normalizzi gli URL prima del loro confronto, quindi questo deve essere risolto nella suite di test: navigare verso URL deterministici, in modo che la stessa pagina produca lo stesso URL a ogni esecuzione. In pratica, ciò significa solitamente utilizzare dati di test fissi invece di generare nuovi record per ciascuna esecuzione e rimuovere o fissare parametri di query volatili prima della scansione della pagina.

Se un URL non può essere stabilizzato in alcun modo, puoi escluderlo completamente dai tuoi risultati con excludeUrlPatterns, anche se ciò significa che la pagina non viene affatto scansionata piuttosto che tracciata correttamente. Vedere Escludere gli URL dall'analisi per i dettagli.

Vedi anche

• Riferimento API per JavaScript e TypeScript Documentazione completa per runOptions e altre opzioni di configurazione
• AxeRunOptions Classe Riferimento API Java per le opzioni di runtime
• Glossario: Duplicato Comprendere come Axe Developer Hub identifica i problemi duplicati