Visão Geral das APIs do Java Watcher

A integração Axe Watcher Java fornece um SDK abrangente para adicionar testes automáticos de acessibilidade aos conjuntos de testes Selenium e Playwright Java. Esta integração analisa automaticamente as páginas da web em busca de problemas de acessibilidade e envia os resultados para o Axe Developer Hub para rastreamento e análise.

Componentes Centrais

Classes Principais

AxeWatcher - O ponto de entrada principal para a integração com Selenium. Esta classe lida com a configuração das opções do navegador e o encapsulamento das instâncias do WebDriver para habilitar o teste de acessibilidade.

AxeWatcherPlaywright - O ponto de entrada principal para a integração com Playwright. Lida com a configuração de LaunchPersistentContextOptions e o encapsulamento das instâncias de Page.

AxeWatcherOptions - Classe de configuração que define como o Axe Watcher opera, incluindo chaves de API, URLs de servidores, IDs de construção para testes paralelos e vários comportamentos de teste. Usada por ambas as integrações Selenium e Playwright.

AxeWatcherGitInfo - Contém metadados Git explícitos para execuções de teste onde a detecção automática de Git não está disponível ou é pouco confiável. Passe para AxeWatcherOptions.setGitInfo() para ignorar a detecção automática.

ConfigurationOverrides - Permite substituir as configurações globais de acessibilidade, incluindo padrões de acessibilidade (WCAG 2.1 AA, WCAG 2.2 AA, etc.), melhores práticas e regras experimentais.

Integração com Driver

AxeWatcherDriver - Interface que estende o Selenium WebDriver padrão para fornecer acesso à funcionalidade de teste de acessibilidade através do método axeWatcher().

AxeWatcherController - Fornece controle detalhado sobre quando e como a análise de acessibilidade ocorre no Selenium, com métodos para iniciar, parar, analisar e descarregar os resultados dos testes.

AxeWatcherPlaywrightController - Fornece os mesmos métodos de controle para Playwright, acessível através do envolvimento de AxeWatcherPage.

Classes de Configuração

Opções de Execução

AxeRunOptions - Controla o comportamento avançado em tempo de execução do mecanismo axe-core, incluindo configurações de regras e informações de ancestralidade para violações.

AxeRunOnly - Limita quais regras de acessibilidade são executadas especificando IDs de regras ou tags (por exemplo, "wcag21aa", "melhor-prática").

AxeRunContext - Define o escopo do teste, incluindo ou excluindo elementos DOM específicos usando seletores CSS.

AxeRuleOptions - Habilita ou desabilita regras de acessibilidade individuais pelo ID da regra.

Uso

Configuração 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();

Configuração Avançada

Configurando para uma Instância Regional ou Nuvem Privada

Se sua organização usa uma instância regional, nuvem privada ou local do Axe Developer Hub, defina a URL do servidor como a URL base dessa instância. Caso contrário, você pode omitir setServerUrl() e o padrão https://axe.deque.com é usado.

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"

Padrões de Acessibilidade 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);

Execução Seletiva de Regras

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

Testes Delimitados

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

Restrições Importantes

1. Opções Mutuamente Exclusivas: Não é possível usar ConfigurationOverrides.accessibilityStandard e AxeRunOptions.runOnly simultaneamente
2. Limitações do Navegador: Não suporta modo totalmente sem cabeça ou modo de navegação anônima
3. Ordem de Métodos: Deve chamar configure() antes de criar o ChromeDriver e wrapDriver() depois
4. Descarregamento de Resultados: Sempre chame controller.flush() na desmontagem dos testes para garantir que os resultados sejam enviados para o Axe Developer Hub
5. Limitações de Frame: Os métodos do controlador não funcionam dentro de iframes ou em páginas que não sejam HTTP(S)

Esta integração oferece modos de teste automáticos e manuais, permitindo que as equipes integrem facilmente testes abrangentes de acessibilidade em suítes de teste Selenium Java existentes com mudanças mínimas de código.