Risoluzione dei problemi

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. Problemi che potresti incontrare:

• Se usi Google Chrome versione 139 o successiva, riceverai un errore da Watcher. Usa invece Chrome for Testing, Chromium o 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, WebDriverJS o Java Selenium, devi configurare esplicitamente il tuo setup di test per utilizzare Chrome for Testing o Microsoft Edge. Vedi Utilizzare Chrome per Testing per i passaggi di installazione ed esempi di configurazione specifici della piattaforma.

Vedi Piattaforme di Test Automatizzate per ulteriori informazioni sul software supportato con Watcher.

Microsoft Edge non funziona con Java Selenium

Se i tuoi test Java Selenium generano un IllegalStateException con il messaggio Il supporto per Microsoft Edge richiede Selenium 4 o più recente, il tuo progetto sta usando Selenium 3. Il EdgeOptions di Selenium 3 è destinato al vecchio browser EdgeHTML, che Axe Watcher non supporta. Aggiorna selenium-java alla versione 4.x per testare su Microsoft Edge, oppure continua a testare su Chrome for Testing o Chromium con ChromeOptions e ChromeDriver, che l'integrazione Java Selenium supporta su Selenium 3.141.59 e versioni successive.

Nessun risultato da Microsoft Edge con WebdriverIO

Se i tuoi test WebdriverIO vengono eseguiti su Microsoft Edge, si completano senza errori e non producono risultati in Axe Developer Hub, controlla la tua versione di Watcher. Usare Microsoft Edge con WebdriverIO richiede Watcher 4.6.0 o versioni successive.

Nelle versioni precedenti, Watcher inviava le sue opzioni del browser alla capacità goog:chromeOptions. Il driver Microsoft Edge legge invece queste opzioni da ms:edgeOptions, quindi le opzioni sono state ignorate e non è stata eseguita alcuna analisi. Nulla è fallito, ed è per questo che i test sono passati con un insieme di risultati vuoto. Aggiorna alla versione 4.6.0 o successive per risolvere il problema.

La proprietà args di una capacità del browser non è valida

Se Watcher segnala che la proprietà args della tua capacità del browser goog:chromeOptions o ms:edgeOptions deve essere un array di stringhe, imposta args su un array di flag della riga di comando del browser, oppure rimuovila:

capabilities: {
  browserName: 'MicrosoftEdge',
  'ms:edgeOptions': {
    args: ['--window-size=1280,720']
  }
}

Sono rifiutati valori come una singola stringa, un oggetto o un array contenente qualcosa che non è una stringa. Watcher 4.5.0 e versioni precedenti accettavano alcuni di questi e fallivano successivamente con un errore non correlato.

Problemi di accessibilità non rilevati all’interno di un iframe cross-origin

Se la tua analisi ha esito positivo ma i tuoi risultati non contengono nulla da un <iframe> servito da un'origine diversa rispetto alla pagina testata, quel frame non è stato analizzato. Watcher analizza sempre i frame con la stessa origine, ma analizza un frame cross-origin solo quando elenchi l'origine di quel frame:

• (JavaScript o TypeScript) allowedOrigins
• (Java) setAllowedOrigins()

axe: {
  allowedOrigins: [ 'https://pay.example.com' ]
}

Non includere l'origine della tua applicazione, che è sempre consentita.

Per confermare quali origini sono state ignorate, cerca la diagnostica cross_origin_frame_not_allowlisted. Viene riportata indipendentemente dal fatto che tu abbia impostato l'opzione o meno, elenca le origini cross-origin non analizzate e stampa la linea di configurazione che puoi incollare. Le diagnosticazioni appaiono solo nell'output di debug: imposta DEBUG=axe-watcher:* quando esegui i tuoi test (JavaScript o TypeScript), o configura il tuo framework di logging per mostrare i messaggi DEBUG per Axe Watcher (Java). Con l'integrazione Java Selenium, puoi anche attivare il logging di debug con enableDebugLogger().

Se i risultati sono ancora mancanti dopo aver elencato l'origine:

• Il frame ha un attributo sandbox che omette allow-same-origin, riportato come cross_origin_frame_unscannable. Il frame ha quindi un'origine opaca che nessuna voce nella tua lista può nominare. Aggiungi allow-same-origin all'attributo sandbox.
• Il frame si reindirizza lontano dall'origine nel suo src, come un dominio apex che si reindirizza a www, o http che si reindirizza a https. Elenca l'origine su cui il frame effettivamente termina.
• Il frame è nidificato a più di un livello di profondità. Le diagnosticazioni di copertura sono riportate dalla pagina di livello superiore riguardo ai frame che incorpora direttamente, quindi un frame profondamente nidificato non viene segnalato.

Se l'analisi fallisce totalmente piuttosto che riportare sottostime, cerca la diagnostica cross_origin_frame_timed_out: un frame ha risposto al ping iniziale di Watcher ma non ha restituito i risultati in tempo. Rimuovi quell'origine dalla tua lista o aumenta runOptions.frameWaitTime.

Se il frame è analizzato ma i suoi risultati non riflettono ciò che il tuo test ha fatto all'interno, la causa è l'analisi automatica. Questa non può rilevare le modifiche effettuate all'interno di un frame, quindi un frame consentito è analizzato a partire dall'ultima modifica alla pagina di livello superiore. Chiama analyze() tu stesso dopo aver interagito con il contenuto all'interno di un frame. Questo è un problema separato da Nessun stato delle pagine catturato dopo il passaggio a un frame figlio, che si applica quando il contesto del browser è spostato nel frame.

Consulta Analizza iframes cross-origin per il quadro completo.

Origini respinte da allowedOrigins

Se Watcher segnala che una voce allowedOrigins non è valida, la voce non è un'origine semplice che può essere confrontata con un frame. Ogni voce necessita di uno schema (http o https), un host e un porto opzionale, senza nient'altro. Cause comuni:

• Un wildcard, come https://*.example.com. Nomina esplicitamente ogni origine.
• Un path, una query string, un frammento o delle credenziali, come https://pay.example.com/checkout.
• Uno schema mancante, come pay.example.com.
• Uno schema diverso da http o https.
• Un dominio contenente caratteri al di fuori dell'alfabeto inglese, come café.example.com. Utilizza invece la forma punycode.

Watcher rifiuta questi invece di ignorarli, perché una voce che non corrisponde all'origine reale di un frame lascerebbe il frame non analizzato mentre il tuo test risulterebbe ancora un successo. Vedi Analizza iframes cross-origin.

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 attuale del browser verso un frame figlio usando switchToFrame() (WebdriverIO o WebDriverJS) o switchTo().frame() (Java Selenium), Axe Watcher non catturerà gli stati della pagina per qualsiasi azione compiuta mentre il browser è concentrato sul frame figlio. Axe Watcher cattura gli stati della pagina solo mentre il contesto del browser è sul frame di livello superiore.

Questo è un argomento separato da se l'iframe contenuto è analizzato. Watcher analizza i frame con la stessa origine e i frame cross-origin di cui elenchi l'origine; vedi Analizza iframes cross-origin.

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()

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

(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
  }
}

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.