Übersicht über die Java Watcher APIs

Die Axe Watcher Java-Integration bietet ein umfassendes SDK, um automatisierte Barrierefreiheitstests in Selenium- und Playwright-Java-Test-Suiten einzubinden. Diese Integration analysiert automatisch Webseiten auf Barrierefreiheitsprobleme und sendet die Ergebnisse zur Nachverfolgung und Analyse an das Axe Developer Hub.

Kernkomponenten

Hauptklassen

AxeWatcher - Der primäre Einstiegspunkt für die Selenium-Integration. Diese Klasse verwaltet die Konfiguration von Browseroptionen und das Wrapping von WebDriver-Instanzen, um Barrierefreiheitstests zu ermöglichen.

AxeWatcherPlaywright - Der primäre Einstiegspunkt für die Playwright-Integration. Verwaltet die Konfiguration von LaunchPersistentContextOptions und das Wrapping von Page-Instanzen.

AxeWatcherOptions - Konfigurationsklasse, die definiert, wie Axe Watcher arbeitet, einschließlich API-Schlüssel, Server-URLs, Build-IDs für Paralleltests und verschiedener Testverhalten. Wird von den Selenium- und Playwright-Integrationen verwendet.

AxeWatcherGitInfo - Speichert explizite Git-Metadaten für Testläufe, bei denen die automatische Git-Erkennung unzugänglich oder unzuverlässig ist. Übergibt an AxeWatcherOptions.setGitInfo(), um die Auto-Erkennung zu umgehen.

ConfigurationOverrides - Ermöglicht das Überschreiben globaler Barrierefreiheitskonfigurationen, einschließlich Barrierefreiheitsstandards (WCAG 2.1 AA, WCAG 2.2 AA usw.), bewährter Praktiken und experimenteller Regeln.

Treiberintegration

AxeWatcherDriver - Schnittstelle, die den standardmäßigen Selenium WebDriver erweitert, um den Zugriff auf Barrierefreiheitstest-Funktionalitäten über die axeWatcher()-Methode zu ermöglichen.

AxeWatcherController - Bietet eine feinkörnige Steuerung darüber, wann und wie die Barrierefreiheitsanalyse in Selenium erfolgt, mit Methoden zum Starten, Stoppen, Analysieren und Flushing von Testergebnissen.

AxeWatcherPlaywrightController - Bietet dieselben Steuerungsmethoden für Playwright, zugänglich über den umschlossenen AxeWatcherPage.

Konfigurationsklassen

Laufzeitoptionen

AxeRunOptions - Steuert das erweiterte Laufzeitverhalten der axe-core-Engine, einschließlich Regelkonfigurationen und Vorfahreninformationen für Verstöße.

AxeRunOnly - Begrenzt, welche Barrierefreiheitsregeln durch die Angabe von Regel-IDs oder Tags (z. B. "wcag21aa", "best-practice") ausgeführt werden.

AxeRunContext - Definiert den Testumfang, indem bestimmte DOM-Elemente mittels CSS-Selektoren ein- oder ausgeschlossen werden.

AxeRuleOptions - Ermöglicht das Aktivieren oder Deaktivieren einzelner Barrierefreiheitsregeln anhand der Regel-ID.

Verwendung

Grundlegende Einrichtung

// Configure options
AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY")) // Required. Secret stored in an environment variable.
    .setProjectId(System.getenv("PROJECT_ID")); // Required. Store in an environment variable for easy updates.

// Create watcher and configure Chrome
AxeWatcher watcher = new AxeWatcher(options);
ChromeOptions chromeOptions = watcher.configure(new ChromeOptions());
ChromeDriver chromeDriver = new ChromeDriver(chromeOptions);

// Wrap driver for accessibility testing
WebDriver driver = watcher.wrapDriver(chromeDriver);

// Access the controller for manual control
AxeWatcherController controller = ((AxeWatcherDriver) driver).axeWatcher();

Erweiterte Konfiguration

Konfiguration für eine regionale oder private Cloud-Instanz

Wenn Ihre Organisation eine regionale, private Cloud oder eine lokale Axe Developer Hub-Instanz nutzt, setzen Sie die Server-URL auf die Basis-URL dieser Instanz. Andernfalls können Sie setServerUrl() weglassen und die Standard-https://axe.deque.com wird genutzt.

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setServerUrl(System.getenv("SERVER_URL")); // e.g., "https://axe-eu.deque.com"

Benutzerdefinierte Barrierefreiheitsstandards

ConfigurationOverrides overrides = new ConfigurationOverrides()
    .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
    .setEnableBestPractices(true)
    .setEnableExperimental(false);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY")) // Required. Secret stored in an environment variable.
    .setProjectId(System.getenv("PROJECT_ID")) // Required. Store in an environment variable for easy updates.
    .setConfigurationOverrides(overrides);

Selektive Regelausführung

// Run only specific accessibility tags
AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa", "best-practice"));

AxeRunOptions runOptions = new AxeRunOptions()
    .setRunOnly(runOnly)
    .setAncestry(true);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY")) // Required. Secret stored in an environment variable.
    .setProjectId(System.getenv("PROJECT_ID")) // Required. Store in an environment variable for easy updates.    
    .setRunOptions(runOptions);

Gezielte Tests

// Include only specific elements
AxeRunContext context = new AxeRunContext()
    .setInclude(Arrays.asList("#main-content", ".form-section"))
    .setExclude(Arrays.asList("#header", "#footer"));

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY")) // Required. Secret stored in an environment variable.
    .setProjectId(System.getenv("PROJECT_ID")) // Required. Store in an environment variable for easy updates.
    .setRunContext(context);

Wichtige Einschränkungen

1. Wechselseitig ausschließende Optionen: Kann nicht gleichzeitig sowohl ConfigurationOverrides.accessibilityStandard als auch AxeRunOptions.runOnly verwenden
2. Browser-Einschränkungen: Unterstützt weder den vollständigen Headless-Modus noch den Inkognito-Modus
3. Methodenreihenfolge: Muss configure() aufrufen, bevor ChromeDriver erstellt wird, und wrapDriver() danach
4. Ergebnisverarbeitung: Rufen Sie controller.flush() immer im Test-Teardown auf, um sicherzustellen, dass die Ergebnisse an das Axe Developer Hub gesendet werden
5. Frame-Einschränkungen: Controller-Methoden funktionieren nicht innerhalb von iframes oder auf nicht-HTTP(S)-Seiten

Diese Integration bietet sowohl automatische als auch manuelle Testmodi, die es Teams ermöglichen, umfassende Barrierefreiheitstests nahtlos in bestehende Selenium Java-Test-Suiten mit minimalen Codeänderungen zu integrieren.