Visión general de las API de Java Watcher

La integración de Axe Watcher Java proporciona un SDK completo para añadir pruebas automáticas de accesibilidad a los conjuntos de pruebas de Selenium y Playwright en Java. Esta integración analiza automáticamente las páginas web en busca de problemas de accesibilidad y envía los resultados al Axe Developer Hub para su seguimiento y análisis.

Componentes principales

Clases principales

AxeWatcher: el punto de entrada principal para la integración con Selenium. Esta clase maneja la configuración de las opciones del navegador y la encapsulación de las instancias de WebDriver para habilitar las pruebas de accesibilidad.

AxeWatcherPlaywright: el punto de entrada principal para la integración con Playwright. Maneja la configuración de LaunchPersistentContextOptions y la encapsulación de las instancias de Page.

AxeWatcherOptions: clase de configuración que define cómo opera Axe Watcher, incluyendo claves de API, URLs del servidor, IDs de compilación para pruebas paralelas y varios comportamientos de prueba. Se utiliza tanto en las integraciones con Selenium como con Playwright.

AxeWatcherGitInfo: contiene metadatos explícitos de Git para ejecuciones de prueba donde la detección automática de Git no está disponible o no es confiable. Se pasa a AxeWatcherOptions.setGitInfo() para omitir la detección automática.

ConfigurationOverrides: permite anular las configuraciones globales de accesibilidad, incluyendo los estándares de accesibilidad (WCAG 2.1 AA, WCAG 2.2 AA, etc.), las mejores prácticas y las reglas experimentales.

Integración del controlador

AxeWatcherDriver: interfaz que extiende el WebDriver estándar de Selenium para proporcionar acceso a la funcionalidad de pruebas de accesibilidad a través del método axeWatcher().

AxeWatcherController: proporciona un control detallado sobre cuándo y cómo ocurre el análisis de accesibilidad en Selenium, con métodos para iniciar, detener, analizar y descargar los resultados de las pruebas.

AxeWatcherPlaywrightController: proporciona los mismos métodos de control para Playwright, accesibles a través del AxeWatcherPage encapsulado.

Clases de configuración

Opciones de ejecución

AxeRunOptions: controla el comportamiento avanzado en tiempo de ejecución del motor axe-core, incluyendo configuraciones de reglas e información de ascendencia para las violaciones.

AxeRunOnly: limita qué reglas de accesibilidad se ejecutan especificando IDs de regla o etiquetas (por ejemplo, "wcag21aa", "mejores-prácticas").

AxeRunContext: define el alcance de las pruebas incluyendo o excluyendo elementos específicos del DOM utilizando selectores CSS.

AxeRuleOptions: habilita o deshabilita reglas de accesibilidad individuales por ID de regla.

Uso

Configuración básica

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

Configuración avanzada

Configuración para una instancia en la nube regional o privada

Si su organización utiliza una nube regional, privada o una instancia premisas de Axe Developer Hub, establezca la URL del servidor en la URL base de esa instancia. De lo contrario, puede omitir setServerUrl() y se usará el https://axe.deque.com predeterminado.

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"

Estándares de accesibilidad personalizados

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

Ejecución selectiva de reglas

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

Pruebas delimitadas

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

Restricciones importantes

1. Opciones mutuamente excluyentes: no se pueden usar ambos ConfigurationOverrides.accessibilityStandard y AxeRunOptions.runOnly simultáneamente
2. Limitaciones del navegador: no admite el modo completamente sin cabeza ni el modo incógnito
3. Orden de los métodos: debe llamar a configure() antes de crear ChromeDriver, y a wrapDriver() después
4. Descarga de resultados: siempre llame a controller.flush() en el desmontaje de pruebas para asegurar que los resultados se envíen al Axe Developer Hub
5. Limitaciones de marcos: Los métodos del controlador no funcionan dentro de iframes o en páginas que no son HTTP(S)

Esta integración ofrece tanto modos de prueba automática como manual, permitiendo a los equipos integrar de manera fluida pruebas de accesibilidad integrales en las suites de prueba de Selenium Java existentes con cambios mínimos de código.