Analizzare gli iframe cross-origin

Axe Watcher analizza il contenuto degli elementi dello stesso origine <iframe> insieme al resto della pagina. I frame serviti da un'origine diversi vengono saltati per impostazione predefinita, e i problemi di accessibilità al loro interno sono completamente esclusi dai tuoi risultati.

L'opzione allowedOrigins aderisce all'analisi di questi frame. Nomina le origini che vuoi coprire, e Watcher analizza i frame serviti da esse come parte di ogni analisi della pagina di incorporazione.

Questa opzione richiede Watcher 4.6.0 o successivo ed è disponibile con le integrazioni JavaScript/TypeScript e le integrazioni Java.

Quando Ne Hai Bisogno

Imposta allowedOrigins quando parti significative dell'esperienza utente sono servite da un'altra origine, come un modulo di pagamento ospitato, un widget di prenotazione o pianificazione incorporato, un lettore multimediale con i propri controlli o un widget di aiuto o chat.

Non ne hai bisogno per i frame serviti dalla tua stessa origine, che vengono sempre analizzati.

Configura Origini Consentite

Elenca solo le origini incorporate che vuoi coprire. L'origine della tua applicazione è sempre consentita, quindi non includerla.

JavaScript e TypeScript

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  allowedOrigins: [ 'https://pay.example.com' ]
}

Java

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});
AxeWatcher watcher = new AxeWatcher(options);

Decidi Quali Origini Fidarsi

L'elenco consentito viene applicato in ogni frame, non solo a quello principale, e funziona in entrambe le direzioni: un frame accetta un messaggio solo da un'origine nel proprio elenco e risponde solo a quelle origini. In pratica, ogni frame consente la sua stessa origine, ogni origine che elenchi e, solo quando l'origine del frame è una che hai elencato, l'origine del frame che lo incorpora direttamente, a condizione che l'incorporatore sia o la pagina a livello superiore o un'altra origine che hai elencato.

Quindi, elencare un'origine non le autorizza a rispondere a qualsiasi pagina che si trova a incorporarla. Ciò che autorizza è lo scambio di markup tra quel frame e il suo incorporatore all'interno della pagina di test, ed è per questo che l'elenco dovrebbe rimanere limitato agli embed che ti fidi.

Questo è anche il motivo per cui i caratteri jolly non sono supportati e perché non c'è un'opzione che significhi "analizza ogni frame." Un elenco consentito che non puoi enumerare non è un elenco consentito. Nomina esplicitamente ogni origine e mantieni l'elenco sugli embed di cui effettivamente hai bisogno di copertura.

Considera se la pagina in fase di test visualizza qualcosa di sensibile mentre i tuoi test sono in esecuzione. Se i tuoi dati di test utilizzano dati personali o di pagamento realistici, valutalo rispetto alle origini di terze parti che stai per consentire.

Scrivi Correttamente le Origini

Ogni voce deve essere un'origine e nient'altro: uno schema (http o https), un host e una porta opzionale. Watcher normalizza ciò che fornisci rimuovendo una barra finale e una porta predefinita (:80 per http, :443 per https), mettendo in minuscolo l'host e eliminando i duplicati.

Watcher rifiuta una voce che non può utilizzare segnalando un errore quando la tua configurazione viene letta, invece di lasciare continuare l'esecuzione del test e non analizzare nulla. In Java, setAllowedOrigins() lancia IllegalArgumentException.

Domini Che Contengono Caratteri Non Inglesi

Un dominio che contiene caratteri al di fuori dell'alfabeto inglese, come café.example.com o пример.рф, ha una seconda scrittura equivalente composta solo delle lettere a a z, delle cifre 0 a 9 e dei trattini. Quella scrittura è chiamata punycode, e comincia sempre con xn--. I browser convertono un dominio alla sua forma punycode prima di usarlo, quindi il punycode è la forma con cui Watcher confronta.

Per trovare la forma punycode, visita l'URL del frame e leggi la barra degli indirizzi del tuo browser dopo che la pagina è stata caricata, oppure usa qualsiasi convertitore punycode online.

Non sostituire una scrittura inglese simile, come cafe.example.com per café.example.com. Watcher la accetta, perché è un'origine valida, ma non corrisponde mai all'origine reale del frame, quindi il frame viene lasciato silenziosamente non analizzato.

Le Parole Chiave <same_origin> e <unsafe_all_origins>

Il motore di accessibilità utilizzato da Watcher, axe-core, accetta due parole chiave nella sua impostazione equivalente, e potresti incontrarle nella documentazione di axe-core o in una configurazione che stai migrando:

• <same_origin> significa "l'origine propria di questa pagina." Watcher la accetta, ma non ha effetto, perché la tua propria origine è sempre consentita.
• <unsafe_all_origins> significa "ogni origine, comprese quelle che non hai elencato." Watcher la rifiuta con un errore, per i motivi descritti in Decidi Quali Origini Fidarsi.

Cattura Modifiche Apportate all'Interno di un Frame

L'analisi automatica rileva le modifiche alla pagina principale di livello superiore. Non può rilevare un cambiamento fatto all'interno un frame, indipendentemente dal fatto che quel frame sia dello stesso origine o cross-origin. Un frame consentito viene quindi analizzato dall'ultima modifica alla pagina principale di livello superiore.

Questo è importante quando interagisci con i contenuti all'interno di un frame. L'interazione cambia il contenuto del frame, la pagina principale di livello superiore rimane invariata, e quindi non viene eseguita alcuna analisi automatica:

// Interacting inside the frame doesn't trigger an automatic analysis
await page.frameLocator('#pay').getByRole('button', { name: 'Continue' }).click()

// Analyze explicitly to capture the resulting state
await controller.analyze()

Chiama analyze() dopo l'interazione per catturare lo stato risultante. Un'analisi che richiedi esplicitamente viene sempre eseguita. Vedi Controlla i Tuoi Scans per come ottenere un oggetto controller nel tuo framework di test.

Trova i Frame che Ti Mancano

Watcher segnala i frame cross-origin che ha saltato, indipendentemente dal fatto che tu abbia impostato allowedOrigins. Questo significa che puoi scoprire quali embed mancano nei tuoi risultati prima di configurare qualsiasi cosa.

La cross_origin_frame_not_allowlisted diagnostica nomina ciascuna origine saltata e include la riga allowedOrigins da incollare nella tua configurazione. Su una pagina con molti embed di terze parti, l'elenco è limitato e il resto è riepilogato come "e altri N".

Le diagnosi appaiono solo nell'output di debug e ciascuna viene riportata al massimo una volta per esecuzione del test.

JavaScript e TypeScript: imposta la variabile d'ambiente DEBUG quando esegui i tuoi test.

DEBUG=axe-watcher:* npx playwright test

Java: i controller registrano ogni diagnosi a livello DEBUG, quindi configura il tuo framework di logging in modo da mostrare i messaggi DEBUG per Axe Watcher. Con l'integrazione di Selenium, puoi anche chiamare enableDebugLogger() su AxeWatcher.

Altre due diagnosi riportano frame che sono stati consentiti ma non ancora analizzati. Entrambe sono descritte sotto Limitazioni:

• cross_origin_frame_unscannable, per un frame sandboxato senza allow-same-origin.
• cross_origin_frame_timed_out, per un frame che non ha restituito risultati in tempo.

Se preferisci che la copertura dei frame compaia nei tuoi risultati piuttosto che nell'output di debug, abilita migliori pratiche. La regola frame-tested di axe-core distingue "nessun problema in questo frame" da "questo frame non è mai stato analizzato": un frame a cui Watcher non è riuscito ad accedere è segnalato come necessitante revisione. Poiché è una regola di migliori pratiche, un insieme di regole limitato alle regole WCAG la omette.

I problemi trovati all'interno di un frame sono attribuiti allo stato della pagina che incorpora il frame, non a uno stato della pagina separato.

Limitazioni

La limitazione che è più probabile che incontri è che l'analisi automatica non può vedere le modifiche fatte all'interno di un frame, descritte sotto Cattura le modifiche fatte all'interno di un frame. Il resto è elencato sotto.

Un frame sandboxato necessita di allow-same-origin

Un frame il cui attributo sandbox omette allow-same-origin ha un'origine opaca, che nessuna voce nella lista di permessi può nominare, per cui non può essere analizzato indipendentemente da ciò che elenchi. Una volta elencata la sua origine, Watcher la riporta con la diagnosi cross_origin_frame_unscannable. Fino a quando non lo fai, viene riportata come cross_origin_frame_not_allowlisted come qualsiasi altro frame saltato. Aggiungi allow-same-origin all'attributo sandbox per analizzare il frame.

Solo allow-same-origin conta qui. Un frame sandboxato che omette allow-scripts viene comunque analizzato normalmente, perché lo script di contenuti di Watcher viene eseguito in un mondo isolato ed esegue anche dove gli script della pagina sono bloccati.

Embed che reindirizzano

Un embed il cui src reindirizza a un'altra origine, come un dominio apex che reindirizza a www o http che reindirizza a https, termina su un'origine che non è quella che hai elencato, quindi non viene analizzato. Elenca l'origine su cui il frame termina effettivamente piuttosto che quella nel suo src.

Frame annidati a più di un livello di profondità non vengono riportati

Le diagnosi di copertura dei frame sono riportate dalla pagina di primo livello, riguardo ai frame che include direttamente. Un frame che non poteva essere raggiunto ma è annidato a due o più livelli di profondità non apparirà nel tuo output di debug, anche se il suo contenuto manca dai risultati.

Un frame che non risponde mai fallisce l'analisi

Un frame che risponde al ping iniziale di Watcher ma non restituisce mai risultati fallisce l'analisi completamente anziché sottovalutandola, e Watcher riporta la diagnosi cross_origin_frame_timed_out. Se un embed di terze parti lento causa questo, rimuovi la sua origine da allowedOrigins o alza runOptions.frameWaitTime.

Budget per un'analisi più lenta

Ogni origine che consenti aggiunge il contenuto completo di quel frame a ciascuna analisi della pagina. Il contenuto del frame viene raccolto, trasferito alla pagina di primo livello e combinato con il resto dei risultati, e tutto ciò accade mentre il tuo test attende.

Il tempo che questo aggiunge cresce con la dimensione e la complessità del contenuto del frame, e con il numero di frame che consenti. Con l'analisi automatica abilitata, il costo si ripete a ogni interazione che Watcher analizza, quindi una lunga suite di test con diversi frame consentiti può aggiungere un notevole tempo a un'esecuzione. Due modi per mantenerlo gestibile:

• Limita allowedOrigins agli embed che effettivamente necessiti di includere, piuttosto che a ogni origine di terze parti sulla pagina.
• Considera di abilitarlo per progetto o per suite di test, in modo che le suite che non eseguono contenuti incorniciati non ne sostengano il costo.

Se vuoi misurare l'effetto sulla tua suite, cronometra un'esecuzione rappresentativa prima e dopo aver abilitato l'opzione.

Timeout

Poiché l'analisi di un frame cross-origin include l'attesa per la risposta di quel frame, i timeout predefiniti analyze e flush cambiano da 5000ms a 10000ms quando allowedOrigins è impostato su un array non vuoto. I predefiniti di start e stop rimangono invariati. I valori di timeout che imposti tu stesso vengono sempre usati come definiti, quindi questo influisce solo sui valori predefiniti. Vedi Imposta i timeout.

Questo si applica alle integrazioni JavaScript e TypeScript. Java Watcher attualmente non supporta timeout personalizzati e i suoi valori di timeout non vengono modificati da questa opzione.

Se imposti i tuoi timeout e poi abiliti allowedOrigins, rivedili. Un valore calibrato per una pagina senza contenuti incorniciati potrebbe ora essere troppo stretto.

Argomenti correlati

• Imposta i timeout
• Controlla le tue scansioni
• Migliori pratiche
• Risoluzione dei problemi
• Riferimento API per la versione JavaScript e TypeScript di Watcher
• Opzioni di AxeWatcher