Analyseren van Cross-Origin iframes

Axe Watcher analyseert de inhoud van same-origin <iframe> elementen samen met de rest van de pagina. Frames die van een verschillende origin komen, worden standaard overgeslagen en toegankelijkheidsproblemen erin worden volledig buiten uw resultaten gehouden.

De allowedOrigins optie kiest ervoor om die frames te analyseren. U geeft de origins aan die u wilt dekken, en Watcher analyseert frames die ervan worden geserveerd als onderdeel van elke analyse van de insluitende pagina.

Deze optie vereist Watcher 4.6.0 of later, en is beschikbaar met de JavaScript/TypeScript-integraties en de Java-integraties.

Wanneer U Dit Nodig Heeft

Stel allowedOrigins in wanneer betekenisvolle delen van uw gebruikerservaring van een andere origin worden geserveerd, zoals een gehost betalingsformulier, een ingesloten boekings- of planningswidget, een mediaplayer met eigen bedieningselementen, of een hulp- of chatwidget.

U heeft het niet nodig voor frames die van uw eigen origin komen, die altijd worden geanalyseerd.

Geconfigureerde Toegestane Origins

Noem alleen de ingesloten origins die u wilt dekken. De origin van uw eigen applicatie is altijd toegestaan, dus hoef die niet op te nemen.

JavaScript en 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);

Bepaal Welke Origins te Vertrouwen

De allowlist wordt toegepast in elk frame, niet alleen in het bovenste, en werkt in beide richtingen: een frame accepteert alleen een bericht van een origin in zijn eigen lijst en antwoordt alleen aan die origins. In de praktijk staat elk frame zijn eigen origin toe, elke origin die u vermeldt, en, alleen wanneer de eigen origin van dat frame er een is die u heeft opgesomd, de origin van het frame dat het direct insluit, mits die insluiter ofwel de bovenliggende pagina is of een andere origin die u heeft vermeld.

Dus een origin opsommen autoriseert het niet om te antwoorden aan welke pagina dan ook die het toevallig insluit. Wat het wel autoriseert is de uitwisseling van markup tussen dat frame en zijn insluiter binnen de te testen pagina, en daarom moet de lijst beperkt blijven tot insluitingen die u vertrouwt.

Dit is ook waarom wildcards niet worden ondersteund en waarom er geen optie is die betekent "analyseer elk frame." Een allowlist die u niet kunt opsommen is geen allowlist. Noem elke origin expliciet en houd de lijst beperkt tot de insluitingen die u daadwerkelijk nodig heeft te dekken.

Overweeg of de te testen pagina iets gevoeligs weergeeft terwijl uw tests worden uitgevoerd. Als uw testopstellingen realistische persoonlijke of betalingsgegevens gebruiken, weeg dat dan af tegen de derde partij origins die u op het punt staat toe te staan.

Schrijf de Origins Correct Op

Elke vermelding moet een origin zijn en niets anders: een schema (http of https), een host en een optionele poort. Watcher normaliseert wat u opgeeft door een achterwaartse schuine streep en een standaardpoort te verwijderen (:80 voor http, :443 voor https), de host in kleine letters te zetten en duplicaten te verwijderen.

Watcher weigert een vermelding die hij niet kan gebruiken door een fout te rapporteren wanneer uw configuratie wordt gelezen, in plaats van de test door te laten gaan en niets te analyseren. In Java, setAllowedOrigins() gooit IllegalArgumentException.

Domeinen Die Niet-Engelse Karakters Bevatten

Een domein dat karakters buiten het Engelse alfabet bevat, zoals café.example.com of пример.рф, heeft een tweede, equivalente spelling die alleen bestaat uit de letters a tot z, de cijfers 0 tot 9 en koppeltekens. Die spelling wordt punycode genoemd en begint altijd met xn--. Browsers zetten een domein om in zijn punycode-vorm voordat het wordt gebruikt, dus punycode is de vorm waartegen Watcher vergelijkt.

Om de punycode-vorm te vinden, bezoekt u de URL van het frame en leest u de adresbalk van uw browser nadat de pagina is geladen, of gebruikt u een online punycode-converter.

Vervang geen gelijkende Engelse spelling, zoals cafe.example.com voor café.example.com. Watcher accepteert het, omdat het een geldige origin is, maar het komt nooit overeen met de echte origin van het frame, dus het frame wordt stilzwijgend niet geanalyseerd.

De <same_origin> en <unsafe_all_origins> Trefwoorden

De toegankelijkheidsengine die Watcher gebruikt, axe-core, accepteert twee trefwoorden in zijn eigen equivalente instelling en u kunt ze tegenkomen in axe-core documentatie of in een configuratie die u migreert:

• <same_origin> betekent "de eigen origin van deze pagina." Watcher accepteert het, maar het heeft geen effect, omdat uw eigen origin altijd is toegestaan.
• <unsafe_all_origins> betekent "elke origin, inclusief degene die u niet heeft opgesomd." Watcher wijst het af met een fout, om de redenen die zijn beschreven in Bepaal Welke Origins te Vertrouwen.

Vang Veranderingen Binnen een Frame op

Automatische analyse detecteert veranderingen in de bovenliggende pagina. Het kan geen verandering binnen een frame detecteren, of dat frame nu same-origin of cross-origin is. Een toegestaan frame wordt daarom geanalyseerd vanaf de laatste wijziging in de bovenliggende pagina.

Dit is van belang wanneer u interageert met inhoud binnen een frame. De interactie verandert de inhoud van het frame, maar de bovenliggende pagina blijft ongewijzigd, waardoor er geen automatische analyse plaatsvindt:

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

Roep analyze() aan na de interactie om de resulterende staat te registreren. Een analyse die u expliciet aanvraagt, wordt altijd uitgevoerd. Zie Beheer Uw Scans voor hoe u een controller-object in uw testframework kunt verkrijgen.

Vind de Frames Die U Mist

Watcher rapporteert over de cross-origin frames die hij heeft overgeslagen, ongeacht of je allowedOrigins hebt ingesteld. Dit betekent dat je kunt ontdekken welke embeds ontbreken in je resultaten voordat je iets configureert.

De cross_origin_frame_not_allowlisted diagnose noemt elke overgeslagen oorsprong en bevat de allowedOrigins regel om in je configuratie te plakken. Op een pagina met veel inhoud van derden wordt de lijst ingekort en de rest samengevat als „en N meer“.

Diagnoses verschijnen alleen in debugoutput, en elke wordt maximaal één keer per testrun gerapporteerd.

JavaScript en TypeScript: stel de DEBUG omgevingsvariabele in wanneer je je tests uitvoert.

DEBUG=axe-watcher:* npx playwright test

Java: de controllers loggen elke diagnose op DEBUG niveau, dus configureer je logframework om DEBUG berichten voor Axe Watcher te tonen. Met de Selenium-integratie kun je ook enableDebugLogger() aanroepen op AxeWatcher.

Twee andere diagnoses rapporteren frames die waren toegestaan maar toch niet geanalyseerd. Beide worden beschreven onder Beperkingen:

• cross_origin_frame_unscannable, voor een frame gesandboxed zonder allow-same-origin.
• cross_origin_frame_timed_out, voor een frame dat niet op tijd resultaten retourneerde.

Als je liever hebt dat frame-coverage in je resultaten verschijnt dan in debugoutput, schakel dan best practices in. De axe-core frame-tested regel onderscheidt „geen problemen in dit frame“ van „dit frame is nooit geanalyseerd“: een frame dat Watcher niet kon bereiken, wordt gemeld als zijnde aan beoordeling toe. Omdat het een best-practice regel is, wordt het door een regelsysteem beperkt tot WCAG-regels weggelaten.

Problemen gevonden binnen een frame worden toegeschreven aan de paginastatus van de pagina die het frame insluit, niet aan een aparte paginastatus.

Beperkingen

De beperking die je waarschijnlijk het eerst tegenkomt, is dat automatische analyse geen wijzigingen ziet die binnen een frame zijn aangebracht, beschreven onder Wijzigingen in een frame vastleggen. De rest staat hieronder.

Een gesandboxd frame heeft allow-same-origin nodig

Een frame waarvan het sandbox attribuut allow-same-origin weglaat, heeft een ondoorzichtige oorsprong, die geen whitelist-vermelding kan benoemen, zodat het niet geanalyseerd kan worden, ongeacht wat je opsomt. Zodra je zijn oorsprong vermeldt, rapporteert Watcher het met de cross_origin_frame_unscannable diagnose. Totdat je dat doet, wordt het gerapporteerd als cross_origin_frame_not_allowlisted net als elk ander overgeslagen frame. Voeg allow-same-origin toe aan het sandbox attribuut om het frame te analyseren.

Alleen allow-same-origin is hier van belang. Een gesandboxd frame dat allow-scripts weglaat, wordt nog steeds normaal geanalyseerd, omdat het inhoudscript van Watcher in een geïsoleerde wereld draait en ook wordt uitgevoerd waar de eigen scripts van de pagina worden geblokkeerd.

Insluitingen die doorverwijzen

Een insluiting waarvan de src omleidt naar een andere oorsprong, zoals een apex-domein dat omleidt naar www of http dat omleidt naar https, eindigt op een oorsprong die niet degene is die je hebt opgegeven, dus wordt het niet geanalyseerd. Vermeld de oorsprong waarop het frame uiteindelijk terechtkomt in plaats van die in zijn src.

Frames die meer dan één niveau diep genest zijn, worden niet gerapporteerd

Diagnoses van frame-coverage worden gerapporteerd vanaf de bovenliggende pagina, over de frames die het direct insluit. Een frame dat niet kon worden bereikt maar twee of meer niveaus diep genest is, verschijnt niet in je debugoutput, ook al ontbreken de inhoud ervan in de resultaten.

Een frame dat nooit reageert faalt in de analyse

Een frame dat de eerste ping van Watcher beantwoordt, maar nooit resultaten retourneert, faalt in de analyse in plaats van het te onderrapporteren, en Watcher rapporteert de cross_origin_frame_timed_out diagnose. Als een traag extern gedeelte dit doet, verwijder het dan uit de allowedOrigins of verhoog runOptions.frameWaitTime.

Budget voor langzamere analyse

Elke oorsprong die je toestaat, voegt de volledige inhoud van dat frame toe aan elke analyse van de pagina. De inhoud van het frame wordt verzameld, overgebracht naar de bovenliggende pagina en gecombineerd met de rest van de resultaten, en dat alles gebeurt terwijl je test wacht.

De hoeveelheid tijd die dit toevoegt, groeit met de grootte en complexiteit van de ingelijste inhoud en met het aantal frames dat je toestaat. Met automatische analyse ingeschakeld, herhaalt de kost zich bij elke interactie die Watcher analyseert, dus een lange testsuite met verschillende toegestane frames kan een aanzienlijke hoeveelheid tijd toevoegen aan een run. Twee manieren om het beheersbaar te houden:

• Beperk allowedOrigins tot de insluitingen die je daadwerkelijk nodig hebt, in plaats van elke externe oorsprong op de pagina.
• Overweeg het in te schakelen per project of per testsuite, zodat suites die geen ingelijste inhoud oefenen er niet voor betalen.

Als je de impact op je eigen suite wilt meten, tijd dan een representatieve run vóór en na het inschakelen van de optie.

Timeouts

Omdat het analyseren van een cross-origin frame inhoudt dat er gewacht wordt tot dat frame reageert, veranderen de standaard analyze en flush timeouts van 5000ms naar 10000ms wanneer allowedOrigins is ingesteld op een niet-lege array. De start en stop standaarden blijven ongewijzigd. Timeoutwaarden die je zelf instelt worden altijd gebruikt zoals gegeven, dus dit beïnvloedt alleen de standaarden. Zie Timeouts instellen.

Dit geldt voor de JavaScript- en TypeScript-integraties. Java Watcher ondersteunt momenteel geen aangepaste timeouts, en de timeoutwaarden worden door deze optie niet gewijzigd.

Als je je eigen timeouts instelt en vervolgens allowedOrigins inschakelt, controleer ze dan. Een waarde die is afgestemd op een pagina zonder ingelijste inhoud kan nu te krap zijn.

Verwante onderwerpen

• Timeouts instellen
• Beheer je scans
• Beste praktijken
• Probleemoplossing
• API-referentie voor de JavaScript- en TypeScript-versie van Watcher
• AxeWatcherOptions