Panoramica delle API di Java Watcher

L'integrazione di Axe Watcher con Java fornisce un SDK completo per aggiungere test di accessibilità automatizzati alle suite di test Java di Selenium e Playwright. Questa integrazione analizza automaticamente le pagine web per rilevare problemi di accessibilità e invia i risultati all'Axe Developer Hub per monitoraggio e analisi.

Componenti Principali

Classi Principali

AxeWatcher - Il punto di ingresso principale per l'integrazione con Selenium. Questa classe gestisce la configurazione delle opzioni del browser e l'incapsulamento delle istanze di WebDriver per abilitare i test di accessibilità.

AxeWatcherPlaywright - Il punto di ingresso principale per l'integrazione con Playwright. Gestisce la configurazione di LaunchPersistentContextOptions e l'incapsulamento delle istanze di Page.

AxeWatcherOptions - Classe di configurazione che definisce come opera Axe Watcher, incluse le chiavi API, gli URL dei server, gli ID di build per test paralleli e vari comportamenti di test. Usato sia dalle integrazioni con Selenium che con Playwright.

AxeWatcherGitInfo - Contiene i metadati Git espliciti per i test in cui il rilevamento automatico di Git non è disponibile o affidabile. Passare a AxeWatcherOptions.setGitInfo() per evitare il rilevamento automatico.

ConfigurationOverrides - Consente di sovrascrivere le impostazioni globali di configurazione dell'accessibilità, incluse le norme di accessibilità (WCAG 2.1 AA, WCAG 2.2 AA, ecc.), le migliori pratiche e le regole sperimentali.

Integrazione con il Driver

AxeWatcherDriver - Interfaccia che estende il Selenium WebDriver standard per fornire accesso a funzionalità di test di accessibilità tramite il metodo axeWatcher().

AxeWatcherController - Fornisce controllo granulare su quando e come si verifica l'analisi dell'accessibilità in Selenium, con metodi per avviare, fermare, analizzare e svuotare i risultati dei test.

AxeWatcherPlaywrightController - Fornisce gli stessi metodi di controllo per Playwright, accessibili tramite il AxeWatcherPage incapsulato.

Classi di Configurazione

Opzioni di Runtime

AxeRunOptions - Controlla il comportamento avanzato di runtime del motore axe-core, incluse le configurazioni delle regole e le informazioni genealogiche per le violazioni.

AxeRunOnly - Limita quali regole di accessibilità vengono eseguite specificando ID regola o tag (ad esempio, "wcag21aa", "best-practice").

AxeRunContext - Definisce il campo di applicazione dei test includendo o escludendo specifici elementi DOM utilizzando selettori CSS.

AxeRuleOptions - Attiva o disattiva singole regole di accessibilità tramite l'ID della regola.

Uso

Impostazione di Base

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

Configurazione Avanzata

Configurazione per un'Istanza Cloud Regionale o Privata

Se la tua organizzazione utilizza un'Axe Developer Hub istanziato in locale, in cloud privato o regionale, imposta l'URL del server all'URL base di quell'istanza. Altrimenti, puoi omettere setServerUrl() e verrà utilizzato il https://axe.deque.com predefinito.

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"

Standard di Accessibilità Personalizzati

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

Esecuzione Selettiva delle Regole

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

Test Mirati

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

Vincoli Importanti

1. Opzioni Mutuamente Esclusive: Non è possibile utilizzare contemporaneamente ConfigurationOverrides.accessibilityStandard e AxeRunOptions.runOnly
2. Limitazioni del Browser: Non supporta la modalità completamente headless o la modalità incognito
3. Ordine dei Metodi: È necessario chiamare configure() prima di creare ChromeDriver, e wrapDriver() dopo
4. Svuotamento dei Risultati: Chiama sempre controller.flush() durante il teardown del test per assicurarti che i risultati siano inviati all'Axe Developer Hub
5. Limitazioni dei Frame: I metodi del controller non funzionano all'interno di iframe o su pagine non HTTP(S)

Questa integrazione offre sia modalità di test automatiche che manuali, consentendo ai team di integrare senza problemi test di accessibilità completi nei test suite esistenti di Selenium Java con minimi cambiamenti al codice.