Usando Seletores Dinâmicos

Ao testar páginas que geram IDs ou nomes de classes dinâmicas a cada carregamento, o Axe Watcher pode ter dificuldade em rastrear se os problemas de acessibilidade são duplicados em diferentes execuções dos testes. Este artigo explica como configurar o Watcher para lidar corretamente com esses cenários. Um URL dinâmico causa o mesmo sintoma por uma razão diferente e precisa de uma correção diferente, abordada em URLs Dinâmicos abaixo.

O Problema com Seletores Dinâmicos

Por padrão, o Axe Watcher usa seletores CSS que incluem IDs e classes de elementos para identificar onde ocorrem problemas de acessibilidade. Por exemplo, um problema pode ser relatado em:

iframe#main-iframe

Essa abordagem funciona bem quando os IDs e classes da sua página permanecem consistentes entre os carregamentos. No entanto, muitas aplicações web modernas geram identificadores dinâmicos que mudam a cada renderização da página, como:

• #component-a1b2c3d4
• .form-field-xyz789

O Axe Watcher também envia um XPath para cada elemento, e o Axe Developer Hub trata uma correspondência em qualquer seletor como sendo o mesmo elemento. Como um XPath nunca inclui nomes de classes, uma página cujos nomes de classes são dinâmicos é frequentemente rastreada corretamente sem necessidade de configuração adicional. Um XPath, por outro lado, inclui o ID de um elemento quando esse ID é único na página, produzindo um caminho como //div[@id='component-a1b2c3d4']. Um ID dinâmico, portanto, altera o seletor CSS e o XPath juntos, não deixando nada estável para correspondência.

Quando os identificadores mudam entre execuções de teste desta maneira, o Axe Watcher não consegue determinar se um problema é uma duplicação de um problema já detectado ou uma nova ocorrência. Isso pode resultar em:

• O mesmo problema sendo relatado como "novo" e "resolvido" em cada execução de teste
• Rastreamento impreciso do seu progresso de acessibilidade ao longo do tempo
• Dificuldade em identificar quais problemas foram realmente corrigidos

A Solução: Habilitar Rastreamento de Ancestralidade

Para lidar com seletores dinâmicos, defina a opção ancestry como true na configuração do seu runOptions. Quando ativado, o Axe Watcher utiliza a posição do elemento dentro da árvore DOM em vez de depender de IDs e classes para localizar elementos entre as execuções de teste.

Com ancestry ativado, um seletor que anteriormente parecia assim:

iframe#main-iframe

Incluirá em vez disso o caminho completo a partir do elemento raiz:

html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

Este seletor posicional permanece consistente entre carregamentos de página, mesmo quando IDs e classes mudam, permitindo que o Axe Watcher rastreie com precisão problemas duplicados.

Exemplos de Configuração

JavaScript e TypeScript

Adicione a opção ancestry ao runOptions da configuração do seu axe:

const config = {
  axe: {
    apiKey: process.env.ACCESSIBILITY_API_KEY,
    projectId: process.env.PROJECT_ID,
    runOptions: {
      ancestry: true
    }
  }
}

Java

Use o método setAncestry() no objeto AxeRunOptions:

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

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setRunOptions(runOptions);

AxeWatcher watcher = new AxeWatcher(options);

Quando Usar o Rastreamento de Ancestralidade

Ative ancestry: true quando sua aplicação:

• Usa frameworks que geram IDs de componentes dinâmicos (React, Vue, Angular)
• Emprega bibliotecas CSS-in-JS que geram nomes de classes únicos
• Tem campos de formulário ou elementos interativos com identificadores gerados automaticamente
• Mostra contagens inconsistentes de "novo problema" e "problema resolvido" entre as execuções de teste para o que parecem ser os mesmos problemas

Compromissos a Considerar

Embora o rastreamento de ancestralidade resolva o problema dos seletores dinâmicos, há algumas considerações a serem feitas:

• Legibilidade do seletor: Seletores posicionais são mais longos e podem ser mais difíceis de ler ao revisar problemas no Axe Developer Hub.
• Sensibilidade à estrutura do DOM: Se a estrutura do DOM da sua página mudar significativamente entre renderizações (não apenas os IDs/classes), os seletores posicionais também podem mudar.
• Depuração: Ao investigar um problema, você pode achar mais fácil localizar um elemento por um ID significativo do que por sua posição na árvore DOM.

Para a maioria das aplicações com identificadores dinâmicos, os benefícios do rastreamento preciso de problemas superam essas desvantagens.

URLs Dinâmicos

Os seletores de elementos são apenas parte de como o Axe Developer Hub identifica um problema. O URL da página é comparado também, na íntegra, incluindo qualquer string de consulta. Habilitar ancestry não tem efeito sobre esta comparação.

Um URL que varia entre execuções de teste, portanto, produz os mesmos sintomas que um seletor dinâmico, e faz isso de forma mais agressiva: quando um URL não foi visto antes, todos os problemas encontrados nele são relatados como novos, sem que os seletores de elementos sejam consultados. As causas comuns incluem:

• IDs de sessão ou tokens de autenticação carregados na string de consulta
• Carimbos de data/hora ou parâmetros de quebra de cache, como ?v=1738012800
• IDs aleatórios no caminho, como /orders/8f3c1b2a/summary
• Fixtures de teste que geram um registro novo, e portanto um URL novo, a cada execução

Não há opção de configuração que normalize URLs antes de serem comparados, então isso deve ser resolvido na sua suíte de testes: navegue para URLs determinísticos, de modo que a mesma página produza o mesmo URL em cada execução. Na prática, isso geralmente significa semear dados de teste fixos em vez de gerar novos registros por execução, e remover ou fixar parâmetros de consulta voláteis antes de a página ser escaneada.

Se um URL realmente não puder ser estabilizado, você pode mantê-lo fora de seus resultados completamente com excludeUrlPatterns, embora isso signifique que a página não será escaneada de forma alguma, em vez de ser rastreada corretamente. Veja Excluir URLs da Análise para mais detalhes.

Veja Também

• Referência de API para JavaScript e TypeScript Documentação completa para runOptions e outras opções de configuração
• AxeRunOptions Classe Referência de API Java para opções de tempo de execução
• Glossário: Duplicado Entendendo como o Axe Developer Hub identifica problemas duplicados