Analysieren von Cross-Origin iframes

Axe Watcher analysiert die Inhalte von Same-Origin-<iframe> Elementen zusammen mit dem Rest der Seite. Frames, die von einem unterschiedlichen-Ursprung stammen, werden standardmäßig übersprungen, und Barrierefreiheitsprobleme in ihnen werden in Ihren Ergebnissen vollständig ausgelassen.

Die allowedOrigins Option entscheidet sich dafür, diese Frames zu analysieren. Sie benennen die Ursprünge, die Sie abdecken möchten, und Watcher analysiert die von ihnen gelieferten Frames als Teil jeder Analyse der einbettenden Seite.

Diese Option erfordert Watcher 4.6.0 oder neuer und ist verfügbar mit den JavaScript/TypeScript-Integrationen und den Java-Integrationen.

Wann Sie das benötigen

Legen Sie allowedOrigins fest, wenn wesentliche Teile Ihrer Benutzererfahrung von einem anderen Ursprung bereitgestellt werden, wie z. B. ein gehostetes Zahlungsformular, ein eingebettetes Buchungs- oder Terminplanungs-Widget, ein Mediaplayer mit eigenen Steuerungen oder ein Hilfe- oder Chat-Widget.

Sie benötigen es nicht für Frames, die von Ihrem eigenen Ursprung bereitgestellt werden, da diese immer analysiert werden.

Erlaubte Ursprünge konfigurieren

Listen Sie nur die eingebetteten Ursprünge auf, die Sie abdecken möchten. Der Ursprung Ihrer eigenen Anwendung ist immer erlaubt, also schließen Sie ihn nicht ein.

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

Entscheiden Sie, welchen Ursprüngen Sie vertrauen

Die Allowlist wird in jedem Frame angewendet, nicht nur im obersten, und sie funktioniert in beide Richtungen: Ein Frame akzeptiert nur eine Nachricht von einem Ursprung in seiner eigenen Liste und antwortet nur diesen Ursprüngen. Praktisch erlaubt jeder Frame seinen eigenen Ursprung, jeden von Ihnen aufgelisteten Ursprung und, nur wenn der eigene Ursprung dieses Frames einer der von Ihnen aufgelisteten ist, den Ursprung des Frames, der ihn direkt einbettet, vorausgesetzt, dieser Einbettende ist entweder die oberste Seite oder ein anderer von Ihnen aufgelisteter Ursprung.

Das Auflisten eines Ursprungs berechtigt ihn also nicht, auf jede Seite zu antworten, die ihn zufällig einbettet. Was es berechtigt, ist der Austausch von Markup zwischen diesem Frame und seinem Einbettenden innerhalb der Seite unter Test, weshalb die Liste auf vertrauenswürdige Einbettungen beschränkt bleiben sollte.

Deshalb werden Wildcards nicht unterstützt und es gibt keine Option, die bedeutet „jeden Frame analysieren“. Eine Allowlist, die Sie nicht aufzählen können, ist keine Allowlist. Nennen Sie jeden Ursprung explizit, und halten Sie die Liste auf die Einbettungen beschränkt, die Sie tatsächlich abdecken müssen.

Überlegen Sie, ob die Seite unter Test etwas Sensitives anzeigt, während Ihre Tests laufen. Wenn Ihre Testdaten realistische persönliche oder Zahlungsdaten verwenden, wägen Sie das gegen die Drittanbieter-Ursprünge ab, die Sie erlauben wollen.

Schreiben Sie die Ursprünge korrekt

Jeder Eintrag muss ein Ursprung und nichts anderes sein: ein Schema (http oder https), ein Host und ein optionaler Port. Watcher normalisiert, was Sie bereitstellen, indem er einen abschließenden Schrägstrich und einen Standardport (:80 für http, :443 für https) entfernt, den Host in Kleinbuchstaben umwandelt und Duplikate verwirft.

Watcher lehnt einen Eintrag ab, den er nicht verwenden kann, indem er einen Fehler meldet, wenn Ihre Konfiguration gelesen wird, anstatt den Testlauf fortzusetzen und nichts zu analysieren. In Java erzeugt setAllowedOrigins() eine IllegalArgumentException.

Domänen, die nicht-englische Zeichen enthalten

Eine Domain, die Zeichen außerhalb des englischen Alphabets enthält, wie café.example.com oder пример.рф, hat eine zweite, äquivalente Schreibweise, die nur aus den Buchstaben a bis z, den Ziffern 0 bis 9 und Bindestrichen besteht. Diese Schreibweise wird Punycode genannt und beginnt immer mit xn--. Browser konvertieren eine Domain vor ihrer Verwendung in ihre Punycode-Form, sodass Watcher die Punycode-Form als Vergleichsmaßstab heranzieht.

Um die Punycode-Form zu finden, besuchen Sie die URL des Frames und lesen Sie die Adressleiste Ihres Browsers, nachdem die Seite geladen wurde, oder verwenden Sie einen beliebigen Online-Punycode-Konverter.

Ersetzen Sie keine ähnlich aussehende englische Schreibweise, wie cafe.example.com für café.example.com. Watcher akzeptiert sie, da es sich um einen gültigen Ursprung handelt, aber sie stimmt nie mit dem tatsächlichen Ursprung des Frames überein, sodass der Frame stillschweigend nicht analysiert wird.

Die <same_origin> und <unsafe_all_origins> Schlüsselwörter

Die von Watcher genutzte Barrierefreiheits-Engine axe-core akzeptiert zwei Schlüsselwörter in ihrer eigenen gleichwertigen Einstellung, und Sie könnten ihnen in der axe-core-Dokumentation oder in einer Konfiguration begegnen, die Sie migrieren:

• <same_origin> bedeutet „dieser Seite eigener Ursprung”. Watcher akzeptiert es, aber es hat keine Wirkung, da Ihr eigener Ursprung immer erlaubt ist.
• <unsafe_all_origins> bedeutet „jeder Ursprung, einschließlich derer, die Sie nicht aufgelistet haben“. Watcher lehnt es mit einer Fehlermeldung ab, aus den in Entscheiden Sie, welchen Ursprüngen Sie vertrauen beschriebenen Gründen.

Änderungen innerhalb eines Frames erfassen

Die automatische Analyse erkennt Änderungen an der obersten Seite. Sie kann keine Änderungen erkennen, die innerhalb eines Frames vorgenommen wurden, unabhängig davon, ob dieser Frame same-origin oder cross-origin ist. Ein erlaubter Frame wird daher zum Zeitpunkt der letzten Änderung an der obersten Seite analysiert.

Dies ist von Bedeutung, wenn Sie mit Inhalten innerhalb eines Frames interagieren. Die Interaktion ändert den Inhalt des Frames, die oberste Seite bleibt unverändert, und daher wird keine automatische Analyse durchgeführt:

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

Rufen Sie analyze() nach der Interaktion auf, um den resultierenden Zustand zu erfassen. Eine Analyse, die Sie explizit anfordern, wird immer durchgeführt. Siehe Steuern Sie Ihre Scans, um zu erfahren, wie Sie ein Steuerobjekt in Ihrem Test-Framework erhalten.

Finden Sie die Frames, die Ihnen fehlen

Watcher meldet die Cross-Origin-Frames, die es übersprungen hat, unabhängig davon, ob Sie allowedOrigins festgelegt haben oder nicht. Das bedeutet, dass Sie herausfinden können, welche Einbettungen in Ihren Ergebnissen fehlen, bevor Sie etwas konfigurieren.

Die cross_origin_frame_not_allowlisted-Diagnose benennt jeden übersprungenen Ursprung und enthält die allowedOrigins-Zeile, die Sie in Ihre Konfiguration einfügen können. Bei einer Seite mit vielen Drittanbieter-Einbettungen ist die Liste begrenzt, und der Rest wird als „und N weitere“ zusammengefasst.

Diagnosen erscheinen nur in der Debug-Ausgabe, und jede wird höchstens einmal pro Testlauf gemeldet.

JavaScript und TypeScript: setzen Sie die DEBUG-Umgebungsvariable, wenn Sie Ihre Tests ausführen.

DEBUG=axe-watcher:* npx playwright test

Java: die Controller protokollieren jede Diagnose auf DEBUG-Ebene, daher konfigurieren Sie Ihr Logging-Framework, um DEBUG-Nachrichten für Axe Watcher anzuzeigen. Mit der Selenium-Integration können Sie auch enableDebugLogger() auf AxeWatcher aufrufen.

Zwei andere Diagnosen melden Frames, die erlaubt waren, aber trotzdem nicht analysiert wurden. Beide sind unter Einschränkungen beschrieben:

• cross_origin_frame_unscannable, für ein Frame, das ohne allow-same-origin sandboxed wurde.
• cross_origin_frame_timed_out, für ein Frame, das nicht rechtzeitig Ergebnisse geliefert hat.

Wenn Sie lieber möchten, dass die Frame-Abdeckung in Ihren Ergebnissen als in der Debug-Ausgabe erscheint, aktivieren Sie best practices. Die axe-core frame-tested-Regel unterscheidet „keine Probleme in diesem Frame“ von „dieses Frame wurde nie analysiert“: Ein Frame, das Watcher nicht erreichen konnte, wird als überprüfungsbedürftig gemeldet. Da es sich um eine Best-Practice-Regel handelt, wird eine auf WCAG-Regeln beschränkte Regelsammlung es auslassen.

Probleme, die innerhalb eines Frames gefunden werden, werden dem Seitenstatus der Seite zugeschrieben, die das Frame einbettet, nicht einem eigenen Seitenstatus.

Einschränkungen

Die wahrscheinlichste Einschränkung, auf die Sie stoßen werden, ist, dass die automatische Analyse die innerhalb eines Frames vorgenommenen Änderungen nicht sehen kann, wie unter Änderungen innerhalb eines Frames erfassen beschrieben. Die restlichen Einschränkungen sind unten aufgeführt.

Ein sandboxed Frame benötigt allow-same-origin

Ein Frame, dessen sandbox-Attribut allow-same-origin auslässt, hat einen undurchsichtigen Ursprung, den kein Eintrag auf der Allowlist benennen kann, sodass es unabhängig davon, was Sie auflisten, nicht analysiert werden kann. Sobald Sie seinen Ursprung auflisten, meldet Watcher es mit der cross_origin_frame_unscannable-Diagnose. Bis dahin wird es wie jedes andere übersprungene Frame als cross_origin_frame_not_allowlisted gemeldet. Fügen Sie allow-same-origin dem sandbox-Attribut hinzu, um das Frame zu analysieren.

Nur allow-same-origin ist hier wichtig. Ein sandboxed Frame, das allow-scripts auslässt, wird immer noch normal analysiert, weil das Inhalts-Skript von Watcher in einer isolierten Welt ausgeführt wird und auch dort arbeitet, wo die eigenen Skripte der Seite blockiert sind.

Einbettungen, die umleiten

Eine Einbettung, deren src zu einem anderen Ursprung umleitet, wie beispielsweise eine Apex-Domain, die zu www umleitet, oder http, die zu https umleitet, landet auf einem Ursprung, der nicht derjenige ist, den Sie aufgeführt haben, sodass sie nicht analysiert wird. Listen Sie den Ursprung auf, auf den das Frame tatsächlich endet, anstatt den im src.

Frames, die mehr als eine Ebene tief verschachtelt sind, werden nicht gemeldet

Diagnosen zur Frame-Abdeckung werden von der obersten Seite aus gemeldet, über die Frames, die sie direkt einbettet. Ein Frame, das nicht erreicht werden konnte, aber zwei oder mehr Ebenen tief verschachtelt ist, wird in Ihrer Debug-Ausgabe nicht angezeigt, obwohl sein Inhalt in den Ergebnissen fehlt.

Ein Frame, das niemals antwortet, schlägt die Analyse fehl

Ein Frame, das auf den initialen Ping von Watcher antwortet, aber niemals Ergebnisse liefert, lässt die Analyse scheitern, anstatt sie zu unterberichten, und Watcher meldet die cross_origin_frame_timed_out-Diagnose. Wenn ein langsames Drittanbieter-Embed dies tut, entfernen Sie entweder seinen Ursprung aus allowedOrigins oder erhöhen Sie runOptions.frameWaitTime.

Budget für langsamere Analyse

Jeder Ursprung, den Sie erlauben, fügt den gesamten Inhalt dieses Frames jeder Analyse der Seite hinzu. Der Inhalt des Frames wird gesammelt, an die oberste Seite übertragen und mit den restlichen Ergebnissen kombiniert, und all das passiert, während Ihr Test wartet.

Wie viel Zeit das hinzufügt, wächst mit der Größe und Komplexität des eingebetteten Inhalts und mit der Anzahl der zugelassenen Frames. Bei aktivierter automatischer Analyse tritt diese Kosten bei jeder Interaktion auf, die Watcher analysiert. Eine lange Testsuite mit mehreren erlaubten Frames kann daher eine beträchtliche Menge an Zeit zu einem Durchlauf hinzufügen. Zwei Möglichkeiten, es handhabbar zu halten:

• Begrenzen Sie allowedOrigins auf die Einbettungen, die Sie tatsächlich abgedeckt haben müssen, anstatt auf jeden Drittanbieter-Ursprung auf der Seite.
• Erwägen Sie, es pro Projekt oder pro Testsuite zu aktivieren, sodass Suiten, die keinen eingebetteten Inhalt testen, nicht dafür zahlen müssen.

Wenn Sie den Effekt auf Ihre eigene Suite messen möchten, sollten Sie einen repräsentativen Durchlauf vor und nach dem Aktivieren der Option zeitlich messen.

Timeouts

Da die Analyse eines Cross-Origin-Frames darauf wartet, dass dieses Frame antwortet, ändern sich die Standard-analyze- und flush-Timeouts von 5000 ms auf 10000 ms, wenn allowedOrigins auf ein nicht leeres Array gesetzt ist. Die Standardwerte für start und stop bleiben unverändert. Von Ihnen selbst festgelegte Timeout-Werte werden immer wie angegeben verwendet, sodass dies nur die Standardwerte betrifft. Siehe Timeouts einstellen.

Dies gilt für die JavaScript- und TypeScript-Integrationen. Java Watcher unterstützt derzeit keine benutzerdefinierten Timeouts, und seine Timeout-Werte werden durch diese Option nicht verändert.

Wenn Sie eigene Timeouts festlegen und dann allowedOrigins aktivieren, sollten Sie diese überprüfen. Ein für eine Seite ohne eingebetteten Inhalt abgestimmter Wert könnte nun zu knapp sein.

Verwandte Themen

• Timeouts einstellen
• Ihre Scans steuern
• Best Practices
• Fehlerbehebung
• API-Referenz für die JavaScript- und TypeScript-Version von Watcher
• AxeWatcherOptions