Usando Seletores Dinâmicos

Ao testar páginas que geram IDs de elementos ou nomes de classe dinâmicos a cada carregamento, o Axe Watcher pode ter dificuldade em rastrear se os problemas de acessibilidade são duplicados entre execuções de teste. Este artigo explica como configurar o Watcher para lidar corretamente com esses cenários.

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

Quando esses identificadores mudam entre execuções de teste, o Axe Watcher não pode determinar se um problema é uma duplicata de um problema detectado anteriormente 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.

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