Risoluzione dei problemi
Problemi comuni e soluzioni con Axe Watcher
Watcher supporta solo Chrome per Testing, Chromium o Microsoft Edge
Sebbene il sito web di Axe Developer Hub supporti diversi browser, il pacchetto Watcher supporta solo Google Chrome per Testing, Chromium o Microsoft Edge (JavaScript/TypeScript o Java con Playwright). Problemi che potresti incontrare:
- Se utilizzi Chrome versione 139 o successiva, riceverai un errore da Watcher. Usa invece Chrome for Testing o Chromium (con JavaScript/TypeScript o Java con Playwright, puoi anche usare Microsoft Edge).
- Se utilizzi il browser Electron di Cypress, riceverai un errore. Specifica il browser come Chrome per Testing, Chromium o Microsoft Edge quando invochi Cypress; altrimenti, verrà impostato di default sul browser Electron. Vedi Avvio dei Browser nella documentazione di Cypress per ulteriori informazioni.
Se utilizzi WebdriverIO o WebDriverJS, devi configurare il setup del test per utilizzare esplicitamente Chrome for Testing o Microsoft Edge. Se utilizzi Java Selenium, devi configurare il setup del test per utilizzare esplicitamente Chrome for Testing. Vedi Utilizzare Chrome per Testing per i passaggi di installazione ed esempi di configurazione specifici per la piattaforma.
Vedi Piattaforme di Test Automatizzate per ulteriori informazioni sul software supportato con Watcher.
Risultati Incompleti
Se la tua suite di test utilizza più test runner che operano in parallelo e usano lo stesso ID build non nullo, i risultati di ciascun test runner sostituiranno quelli di altri test runner per lo stesso SHA di commit Git, dando risultati incompleti. Devi assicurarti che ogni test runner usi lo stesso ID build non nullo.
In genere imposti l'ID di build nel tuo AxeConfiguration.
Per ulteriori informazioni sull'uso di runner di test paralleli con diverse piattaforme CI/CD, vedi Esecuzione dei Test in Parallelo.
Errori di Accessibilità Duplicati o Conteggio Errato delle Nuove Problematiche
Se il tuo sito web utilizza ID dinamici o nomi di classi che cambiano ogni volta che la pagina viene ricaricata, è probabile che vedrai errori di accessibilità duplicati, in particolare problemi contrassegnati come nuovi quando i test precedenti mostrano lo stesso problema sullo stesso elemento. (Axe Developer Hub utilizza ID e classi per identificare lo stesso elemento tra i test). Per risolvere questo problema, devi impostare la proprietà ancestry nell'oggetto runOptions nella tua configurazione su true. L'esempio seguente mostra come impostare l'opzione nella tua configurazione:
axe: {
runOptions: {
ancestry: true
}
}Vedi Utilizzo dei Selettori Dinamici per ulteriori indicazioni su come utilizzare i selettori dinamici.
Vedi (JavaScript/TypeScript) runOptions o (Java) AxeWatcherOptions.setRunOptions() per ulteriori informazioni.
Vecchia versione di @axe-core/watcher
Se stai utilizzando la versione 3.18.0 o precedente di @axe-core/watcher, riceverai questo messaggio di avviso:
Axe Developer Hub ora aderisce alle impostazioni definite in Configurazione di Axe, e i test creati da versioni di @axe-core/watcher precedenti alla 3.18.0 generano sessioni che non erano a conoscenza delle impostazioni globali nella Configurazione di Axe. Dovresti aggiornare il tuo pacchetto @axe-core/watcher e rieseguire i test per creare sessioni che rispettano la Configurazione di Axe della tua azienda. Vedi Utilizzo delle configurazioni globali.
Nessun stato delle pagine catturato dopo il passaggio a un frame figlio
Se il tuo test cambia il contesto corrente del browser a un frame figlio utilizzando switchToFrame() (WebdriverIO o WebDriverJS) o switchTo().frame() (Java Selenium), Axe Watcher non catturerà gli stati della pagina per eventuali azioni eseguite mentre il browser è focalizzato sul frame figlio. Axe Watcher può analizzare solo il frame di livello superiore.
Per esempio, in WebdriverIO, la chiamata click() sotto riportata non produrrà uno stato della pagina:
await browser.url('https://example.com')
const iframe = await browser.$('iframe')
await browser.switchToFrame(iframe)
// Actions taken in the child frame will not be analyzed
await button.click()Per riprendere la cattura degli stati delle pagine, passa di nuovo al frame di livello superiore prima di continuare:
// WebdriverIO
await browser.switchToParentFrame()
// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()Cypress non è influenzato da questa limitazione.
Stato della pagina extra generato da cy.screenshot()
Se chiami cy.screenshot() nei tuoi test Cypress, Axe Watcher potrebbe generare uno stato della pagina extra. Quando Cypress scatta uno screenshot, modifica brevemente il DOM per disabilitare le animazioni, e l'osservatore DOM di Axe Watcher può rilevare quella modifica come un cambiamento di stato della pagina. Questo è un comportamento previsto e non influenza l'accuratezza dei tuoi risultati di accessibilità.
Timeout del metodo Controller
Java Watcher attualmente non consente di modificare i valori di timeout.
(Solo JavaScript o TypeScript) Riceverai un messaggio simile al seguente se le chiamate a Controller (definito nella classe base astratta Controller come analyze(), flush(), start(), e stop()) o comandi personalizzati Cypress hanno un timeout:
Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/wa-troubleshooting for more troubleshooting.Il metodo Controller specificato (qui, il metodo flush()) ha richiesto più tempo del previsto e ha causato un timeout. Puoi modificare il tempo predefinito aggiungendo un oggetto timeout alla tua configurazione:
axe: {
timeout: {
flush: 10000
}
}Questi valori di timeout sono indipendenti dal framework di test che stai utilizzando, e potresti anche dover aumentare i valori di timeout per quel framework.
Vedi Impostare i timeout per informazioni sull'uso dei timeout.
Vedi Interfaccia Timeouts e timeouts per ulteriori informazioni. I valori predefiniti dei timeout sono mostrati nella tabella sotto il Interfaccia Timeouts.
Risultati che Non Compaiono
Se hai eseguito la tua suite di test e nessun risultato viene visualizzato in Axe Developer Hub per un determinato progetto, la causa potrebbe essere tra le ragioni nelle seguenti sezioni:
Non configurare Axe Watcher
La tua suite di test modificata deve chiamare il configurazione appropriato per il tuo framework di test prima di eseguire i test. Se non configuri correttamente Axe Watcher, riceverai un messaggio che ti indica di configurare Axe Watcher. Ad esempio, se dimentichi di configurare Axe Watcher con Cypress, vedrai questo messaggio quando esegui la tua suite di test:
Cypress is not configured for axe Watcher. Please ensure that axe Watcher's cypressConfig() is invoked within Cypress's defineConfig() in your cypress.config.js. All tests will fail with this error.Consulta la configurazione istruzioni per esempi di configurazione per il tuo linguaggio e framework di test del browser.
Non Eliminare i Risultati
Devi chiamare la funzione flush() (o il comando personalizzato axeWatcherFlush() in Cypress) per inviare i risultati raccolti ai server di Deque in modo che i risultati possano essere presentati sul sito web di Axe Developer Hub. Solitamente, chiami la funzione flush() nel hook di pulizia della tua piattaforma di automazione.
Ad esempio, nel file support/e2e.js in Cypress, aggiungi la chiamata a afterEach():
// Flush axe-watcher results after each test.
afterEach(() => {
cy.axeWatcherFlush()
})Utilizzo dell'opzione --incognito
Non puoi utilizzare l'opzione da riga di comando --incognito con Chrome; altrimenti, i tuoi test falliranno silenziosamente. Se stai usando la modalità in incognito per evitare di scrivere file memorizzati nella cache su disco (i file memorizzati nella cache sono mantenuti solo in memoria in modalità in incognito), usa i metodi di caching della tua suite di test.
Non impostare le variabili d'ambiente richieste
Se stai sperimentando con gli esempi nel repository watcher-examples su GitHub, nota che gli esempi utilizzano variabili d'ambiente per impostare la chiave API e l'ID progetto, API_KEY e PROJECT_ID.
Test eseguito troppo velocemente
I tuoi test potrebbero essere eseguiti troppo velocemente, scaricando la pagina e liberando le sue risorse prima che Watcher possa analizzarla. Per risolvere questo problema, puoi aggiungere un ritardo alla fine del test per permettere l'analisi della pagina.
Ad esempio, in Cypress, puoi aggiungere un ritardo di 10 secondi (10.000 millisecondi) con il metodo cy.wait():
describe('Visitor', () => {
it('should visit example.com', () => {
cy.visit('https://www.example.com')
cy.wait(10000); })
})Chiave API mancante o non valida
Una chiave API non valida o mancante appare come un file di configurazione non valido in Cypress. Il trace dello stack rivelerà se è non valida o mancante. Una chiave **mancante** risulta nel seguente:
AssertionError [ERR_ASSERTION]: API key is required
at validateApiKey ...(Molte righe del traceback sono state eliminate per brevità.)
Una chiave **non valida** risulta nel seguente trace dello stack (accorciato):
Error: Server responded to https://axe.deque.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
at Response.getBody
...Aiuto
Se non riesci a risolvere il tuo problema, ti preghiamo di contattaci via email in modo che possiamo aiutarti.