Fehlerbehebung

Watcher unterstützt nur Chrome für Tests, Chromium oder Microsoft Edge

Obwohl die Axe Developer Hub-Website mehrere Browser unterstützt, unterstützt das Watcher-Paket nur Google Chrome für Tests, Chromium oder Microsoft Edge. Probleme, auf die Sie stoßen könnten:

• Wenn Sie Google Chrome Version 139 oder später verwenden, erhalten Sie von Watcher einen Fehler. Verwenden Sie stattdessen Chrome for Testing, Chromium oder Microsoft Edge.
• Wenn Sie den Electron-Browser von Cypress verwenden, erhalten Sie einen Fehler. Geben Sie den Browser als Chrome für Tests, Chromium oder Microsoft Edge an, wenn Sie Cypress aufrufen; andernfalls wird standardmäßig der Electron-Browser verwendet. Siehe Browser starten in der Cypress-Dokumentation für weitere Informationen.

Wenn Sie WebdriverIO, WebDriverJS oder Java Selenium verwenden, müssen Sie Ihr Test-Setup explizit so konfigurieren, dass Chrome for Testing oder Microsoft Edge verwendet wird. Siehe Chrome für Tests verwenden für Installationsschritte und plattformspezifische Konfigurationsbeispiele.

Siehe Automatisierte Testplattformen für weitere Informationen über unterstützte Software mit Watcher.

Microsoft Edge schlägt mit Java Selenium fehl

Wenn Ihre Java-Selenium-Tests eine IllegalStateException mit der Nachricht Die Unterstützung für Microsoft Edge erfordert Selenium 4 oder neuer auslösen, verwendet Ihr Projekt Selenium 3. Die EdgeOptions von Selenium 3 zielt auf den veralteten EdgeHTML-Browser ab, den Axe Watcher nicht unterstützt. Aktualisieren Sie selenium-java auf 4.x, um in Microsoft Edge zu testen, oder testen Sie weiterhin in Chrome for Testing oder Chromium mit ChromeOptions und ChromeDriver, die die Java-Selenium-Integration mit Selenium 3.141.59 und höher unterstützt.

Keine Ergebnisse von Microsoft Edge mit WebdriverIO

Wenn Ihre WebdriverIO-Tests gegen Microsoft Edge ausgeführt werden, ohne Fehler abgeschlossen werden und keine Ergebnisse im Axe Developer Hub erzeugen, überprüfen Sie Ihre Watcher-Version. Die Nutzung von Microsoft Edge mit WebdriverIO erfordert Watcher 4.6.0 oder höher.

In früheren Versionen sendete Watcher seine Browser-Optionen an die goog:chromeOptions-Funktionalität. Der Microsoft Edge WebDriver liest diese jedoch von ms:edgeOptions, sodass die Optionen ignoriert wurden und keine Analyse durchgeführt wurde. Es schlug nichts fehl, weshalb die Tests mit einem leeren Ergebnisset bestanden wurden. Aktualisieren Sie auf Version 4.6.0 oder höher, um das Problem zu beheben.

Die args-Eigenschaft einer Browser-Funktionalität ist ungültig

Wenn Watcher meldet, dass die args-Eigenschaft Ihrer goog:chromeOptions- oder ms:edgeOptions-Browser-Funktionalität ein Array von Zeichenfolgen sein muss, setzen Sie args auf ein Array von Browser-Kommandozeilen-Flags oder entfernen Sie es:

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

Werte wie eine einzelne Zeichenfolge, ein Objekt oder ein Array, das etwas anderes als eine Zeichenfolge enthält, werden abgelehnt. Watcher 4.5.0 und früher akzeptierten einige davon und schlugen später mit einem nicht verwandten Fehler fehl.

Barrierefreiheitsprobleme innerhalb eines Cross-Origin-Iframes fehlen

Wenn Ihre Analyse erfolgreich ist, Ihre Ergebnisse jedoch nichts von einem <iframe> enthalten, der von einem anderen Ursprung als die getestete Seite bereitgestellt wird, wurde dieser Frame nicht analysiert. Watcher analysiert immer gleichartige Frames, aber ein Cross-Origin-Frame wird nur analysiert, wenn Sie den Ursprung dieses Frames auflisten:

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

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

Fügen Sie nicht den Ursprung Ihrer eigenen Anwendung hinzu, der immer erlaubt ist.

Um zu bestätigen, welche Ursprünge ausgelassen wurden, suchen Sie das cross_origin_frame_not_allowlisted-Diagnose. Es wird unabhängig davon gemeldet, ob Sie die Option gesetzt haben, es nennt die Cross-Origin-Ursprünge, die nicht analysiert wurden, und es druckt die Konfigurationszeile aus, die Sie einfügen können. Diagnosen erscheinen nur in der Debug-Ausgabe: setzen Sie DEBUG=axe-watcher:*, wenn Sie Ihre Tests ausführen (JavaScript oder TypeScript), oder konfigurieren Sie Ihr Logging-Framework, um DEBUG-Nachrichten für Axe Watcher anzuzeigen (Java). Mit der Java-Selenium-Integration können Sie außerdem das Debug-Logging mit enableDebugLogger() einschalten.

Wenn Ergebnisse fehlen, obwohl Sie den Ursprung aufgelistet haben:

• Der Frame hat ein sandbox-Attribut, das allow-same-origin weglässt, gemeldet als cross_origin_frame_unscannable. Der Frame hat dann einen undurchsichtigen Ursprung, den kein Eintrag in Ihrer Liste benennen kann. Fügen Sie allow-same-origin zum sandbox-Attribut hinzu.
• Der Frame leitet vom Ursprung in seinem src um, wie etwa eine Apex-Domain, die zu www umleitet, oder http, die zu https umleitet. Listen Sie den Ursprung auf, auf dem der Frame tatsächlich landet.
• Der Frame ist mehr als eine Ebene tief verschachtelt. Abdeckungsdiagnosen werden von der obersten Seite über die Frames berichtet, die er direkt einbettet, sodass ein tief verschachtelter Frame nicht gemeldet wird.

Wenn die Analyse vollständig fehlschlägt, anstatt zu wenig zu melden, suchen Sie das cross_origin_frame_timed_out-Diagnose: ein Frame hat auf das erste Ping von Watcher geantwortet, aber keine Ergebnisse rechtzeitig zurückgegeben. Entfernen Sie entweder diesen Ursprung aus Ihrer Liste, oder erhöhen Sie runOptions.frameWaitTime.

Wenn der Frame analysiert wird, aber seine Ergebnisse nicht widerspiegeln, was Ihr Test darin durchgeführt hat, ist die automatische Analyse die Ursache. Sie kann keine Änderungen innerhalb eines Frames erkennen, sodass ein erlaubter Frame zum Zeitpunkt der letzten Änderung der obersten Seite analysiert wird. Rufen Sie analyze() selbst auf, nachdem Sie mit den Inhalten innerhalb eines Frames interagiert haben. Dies ist ein separates Problem von Keine Seitenerfassungen nach dem Wechsel zu einem untergeordneten Frame, das gilt, wenn der Browserkontext in den Frame gewechselt wird.

Sehen Sie Cross-Origin-Iframes analysieren für das vollständige Bild.

Ursprünge, die von allowedOrigins abgelehnt werden

Wenn Watcher meldet, dass ein allowedOrigins-Eintrag ungültig ist, dann ist der Eintrag kein einfacher Ursprung, den er mit einem Frame vergleichen kann. Jeder Eintrag benötigt ein Schema (http oder https), einen Host und einen optionalen Port, ohne irgendetwas anderes. Häufige Ursachen:

• Ein Platzhalter, wie https://*.example.com. Nennen Sie jeden Ursprung explizit.
• Ein Pfad, eine Abfragezeichenfolge, ein Fragment oder Anmeldedaten, wie https://pay.example.com/checkout.
• Ein fehlendes Schema, wie pay.example.com.
• Ein Schema, das weder http noch https ist.
• Eine Domain, die Zeichen außerhalb des englischen Alphabets enthält, wie café.example.com. Verwenden Sie stattdessen die Punycode-Form.

Watcher lehnt diese ab, anstatt sie zu ignorieren, weil ein Eintrag, der nicht mit einem tatsächlichen Ursprung eines Frames übereinstimmt, den Frame unanalyisiert lassen würde, während Ihr Testrun weiterhin als erfolgreich gemeldet wird. Siehe Cross-Origin-Iframes analysieren.

Unvollständige Ergebnisse

Wenn Ihre Testumgebung mehrere Testrunner verwendet, die parallel laufen und dieselbe nicht-leere Build-ID verwenden, überschreiben die Ergebnisse jedes Testrunners die der anderen Testrunner für den gleichen Git-Commit-SHA, was zu unvollständigen Ergebnissen führt. Sie müssen sicherstellen, dass jeder Testrunner dieselbe nicht-leere Build-ID verwendet.

Normalerweise setzen Sie die Build-ID in Ihrer AxeConfiguration.

Für weitere Informationen zur Verwendung von parallelen Testrunnern mit verschiedenen CI/CD-Plattformen siehe Tests parallel ausführen.

Doppelte Barrierefreiheitsfehler oder falsche Anzahl neuer Probleme

Wenn Ihre Website dynamische IDs verwendet, die sich bei jeder Aktualisierung der Seite ändern, werden Sie wahrscheinlich doppelte Barrierefreiheitsfehler sehen, insbesondere Probleme, die als neu markiert sind, wenn frühere Testdurchläufe dasselbe Problem auf demselben Element aufweisen. (Der Axe Developer Hub identifiziert dasselbe Element zwischen Testdurchläufen anhand seines CSS-Selectors und seines XPath, die beide die ID des Elements einbeziehen.) Um dieses Problem zu lösen, müssen Sie die Eigenschaft ancestry im Objekt runOptions in Ihrer Konfiguration auf true setzen. Das folgende Beispiel zeigt, wie die Option in Ihrer Konfiguration festgelegt wird:

axe: {
  runOptions: {
    ancestry: true
  }
}

Weitere Anleitungen zur Verwendung von dynamischen Selektoren finden Sie unter Verwendung dynamischer Selektoren.

Wenn Ihre Fehleranzahl auch nach dem Aktivieren von ancestry noch falsch ist, überprüfen Sie, ob sich die URLs, die Ihre Tests besuchen, zwischen den Durchläufen ändern. Die URL wird in voller Länge verglichen, einschließlich aller Abfragezeichenfolgen, sodass eine Sitzungs-ID oder ein Cache-Busting-Parameter jedes Problem auf der Seite neu erscheinen lässt. Siehe Dynamische URLs.

Siehe (JavaScript/TypeScript) runOptions oder (Java) AxeWatcherOptions.setRunOptions() für weitere Informationen.

Alte Version von @axe-core/watcher

Wenn Sie Version 3.18.0 oder älter von @axe-core/watcher verwenden, erhalten Sie diese Warnmeldung:

Der Axe Developer Hub hält sich jetzt an die in Axe-Konfiguration definierten Einstellungen, und Testruns, die mit Versionen von @axe-core/watcher Version 3.18.0 oder älter erstellt wurden, generieren Sitzungen, die sich der globalen Einstellungen in der Axe-Konfiguration nicht bewusst waren. Sie sollten Ihr @axe-core/watcher-Paket aktualisieren und Ihre Tests erneut ausführen, um Sitzungen zu erstellen, die der Axe-Konfiguration Ihres Unternehmens folgen. Siehe Verwendung globaler Konfigurationen.

Keine Seitenerfassungen nach dem Wechsel zu einem untergeordneten Frame

Wenn Ihr Test den aktuellen Kontext des Browsers auf einen untergeordneten Frame umschaltet, indem er switchToFrame() (WebdriverIO oder WebDriverJS) oder switchTo().frame() (Java Selenium) verwendet, wird Axe Watcher keine Seitenzustände für Aktionen erfassen, die ausgeführt werden, während der Browser auf den untergeordneten Frame fokussiert ist. Axe Watcher erfasst Seitenzustände nur, während der Kontext des Browsers auf dem obersten Frame ist.

Dies ist eine separate Angelegenheit davon, ob Iframe Inhalt analysiert wird. Watcher analysiert gleichartige Frames und Cross-Origin-Frames, deren Ursprung Sie auflisten; siehe Cross-Origin-Iframes analysieren.

Zum Beispiel wird der folgende click()-Aufruf in WebdriverIO keinen Seitenzustand erzeugen:

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

Um die Seitenerfassung wieder aufzunehmen, wechseln Sie vor dem Fortfahren zurück zum obersten Frame:

// WebdriverIO
await browser.switchToParentFrame()

// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()

Playwrights setContent()-Methode wird nicht unterstützt

Axe Watcher unterstützt keine Tests, die Playwrights page.setContent()- oder frame.setContent()-Methoden aufrufen. Diese Einschränkung gilt sowohl für das JavaScript/TypeScript-Paket als auch für die Java-Bibliothek.

Diese Methoden ersetzen das gesamte Dokument, indem sie intern document.write() verwenden, was den Kontext verwirft, auf den Axe Watcher angewiesen ist, um die Seite zu analysieren. Axe Watcher analysiert die Seite bis zum Zeitpunkt des Aufrufs erfolgreich, danach kann Axe Watcher die Seite nicht mehr analysieren oder seine Ergebnisse senden, und Ihr Test schlägt mit Timeout-Fehlermeldungen fehl, die in etwa wie folgt lauten:

Error: Watcher timed out before it could finish analyzing the page state. To resolve this problem, increase the `timeout.analyze` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Error: Watcher timed out sending results to the server. To resolve this problem, increase the `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Anstatt das Markup direkt festzulegen, servieren Sie es von einer URL und navigieren Sie mit page.goto() dahin, damit der Browser das Dokument normal lädt:

// Not supported by Axe Watcher:
await page.setContent('<my-button disabled></my-button>')

// Navigate to a URL that serves the same markup instead:
await page.goto('http://localhost:6006/my-button.html')

Zusätzlicher Seitenzustand erzeugt durch cy.screenshot()

Wenn Sie cy.screenshot() in Ihren Cypress-Tests aufrufen, kann Axe Watcher einen zusätzlichen Seitenzustand erzeugen. Wenn Cypress einen Screenshot macht, ändert es vorübergehend das DOM, um Animationen zu deaktivieren, und der DOM-Beobachter von Axe Watcher kann diese Änderung als Seitenzustandsänderung erkennen. Dies ist ein erwartetes Verhalten und beeinträchtigt nicht die Genauigkeit Ihrer Barrierefreiheitsresultate.

Controller-Methode läuft ab

(Nur JavaScript oder TypeScript) Sie werden eine ähnliche Nachricht erhalten, wenn Aufrufe an die Controller-Methoden (definiert in der Controller-abstrakten Basisklasse als analyze(), flush(), start() und stop()) oder benutzerdefinierten Cypress-Befehlen ablaufen:

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.

Die angegebene Controller-Methode (hier die flush()-Methode) benötigte mehr als die Standardzeit für den Abschluss und ist abgelaufen. Sie können die Standardzeit ändern, indem Sie ein timeout-Objekt zu Ihrer Konfiguration hinzufügen:

axe: {
  timeout: {
    flush: 10000
  }
}

Siehe Timeouts festlegen für Informationen zur Verwendung von Zeitüberschreitungen.

Siehe Timeouts-Schnittstelle und timeouts für weitere Informationen. Die Standard-Zeitüberschreitungswerte sind in der Tabelle unter der Timeouts-Schnittstelle gezeigt.

Ergebnisse erscheinen nicht

Wenn Sie Ihre Testsuite ausgeführt haben und keine Ergebnisse in Axe Developer Hub für ein bestimmtes Projekt angezeigt werden, könnte die Ursache in den folgenden Abschnitten zu finden sein:

Axe Watcher nicht konfiguriert

Ihre modifizierte Testsuite muss das geeignete Konfigurationsfunktion für Ihr Test-Framework aufrufen, bevor Sie Ihre Tests ausführen. Wenn Sie Axe Watcher nicht richtig konfigurieren, erhalten Sie eine Nachricht, dass Sie Axe Watcher konfigurieren müssen. Wenn Sie beispielsweise vergessen, Axe Watcher mit Cypress zu konfigurieren, sehen Sie diese Nachricht, wenn Sie Ihre Testsuite ausführen:

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.

Konsultieren Sie die Konfiguration Anweisungen für Konfigurationsbeispiele für Ihre Sprache und Ihr Browser-Testframework.

Ergebnisse nicht freigeben

Sie müssen die flush()-Funktion (oder den benutzerdefinierten Befehl axeWatcherFlush() in Cypress) aufrufen, um die gesammelten Ergebnisse zurück an die Server von Deque zu senden, damit die Ergebnisse auf der Website des Axe Developer Hub präsentiert werden können. Normalerweise rufen Sie die flush()-Funktion im Bereinigungshook Ihrer Automatisierungsplattform auf.

Zum Beispiel fügen Sie im support/e2e.js-Datei in Cypress den Aufruf zu afterEach() hinzu:

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Verwendung der Option --incognito

Sie können die --incognito-Befehlszeilenoption nicht mit Chrome verwenden; andernfalls werden Ihre Tests stillschweigend fehlschlagen. Wenn Sie den Inkognito-Modus verwenden, um zu vermeiden, dass zwischengespeicherte Dateien auf die Festplatte geschrieben werden (zwischengespeicherte Dateien werden im Inkognito-Modus nur im Speicher gehalten), verwenden Sie stattdessen die Caching-Methoden Ihrer Testsuite.

Die erforderlichen Umgebungsvariablen nicht setzen

Wenn Sie mit den Beispielen im watcher-examples-Repo auf GitHub experimentieren, beachten Sie, dass die Beispiele Umgebungsvariablen zur Festlegung des API-Schlüssels und der Projekt-ID verwenden, API_KEY und PROJECT_ID.

Test läuft zu schnell

Ihre Tests könnten zu schnell laufen, wodurch die Seite entladen und ihre Ressourcen freigegeben werden, bevor Watcher sie analysieren kann. Um dieses Problem zu beheben, können Sie am Ende des Tests eine Verzögerung einfügen, damit genügend Zeit zur Analyse der Seite bleibt.

Zum Beispiel können Sie in Cypress eine Verzögerung von 10 Sekunden (10.000 Millisekunden) mit der cy.wait()-Methode hinzufügen:

describe('Visitor', () => {
  it('should visit example.com', () => {
    cy.visit('https://www.example.com')
    cy.wait(10000);  })
})

Fehlender oder ungültiger API-Schlüssel

Ein ungültiger oder fehlender API-Schlüssel erscheint als ungültige Konfigurationsdatei in Cypress. Der Stack-Trace wird zeigen, ob er ungültig oder fehlend ist. Ein fehlender-Schlüssel führt zu folgendem Ergebnis:

AssertionError [ERR_ASSERTION]: API key is required
    at validateApiKey ...

(Viele Zeilen des Stack-Traces wurden der Kürze halber gelöscht.)

Ein ungültiger-Schlüssel führt zum folgenden Stack-Trace (verkürzt):

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
...

Hilfe

Wenn Sie Ihr Problem nicht lösen können, bitte mailen Sie uns, damit wir Ihnen helfen können.