Perguntas Frequentes

Conceitos

Qual é a diferença entre um projeto Git e um projeto Gitless?

O Developer Hub organiza seus resultados de forma diferente dependendo se seus testes usam Git:

• Um projeto Git associa resultados de acessibilidade com branches e commits, permitindo que você acompanhe problemas até alterações específicas no código.
• Um projeto Gitless organiza resultados como uma série de execuções de teste ordenadas por timestamp, sem qualquer dado do Git.
• Dados do Git estão disponíveis ao usar o Axe Watcher, o Axe CLI ou o Axe DevTools para Web APIs (que carregam resultados via CLI). Projetos móveis são sempre Gitless.

Veja Entenda Seus Resultados e as entradas do glossário para Git e Gitless para mais detalhes.

O que é o limite de a11y e como posso configurá-lo?

O limite de a11y reflete a tolerância da sua organização para problemas de acessibilidade e determina o que conta como falha em seu pipeline CI/CD:

• Ele é calculado a partir de dois critérios: se todas as questões ou apenas novas questões devem ser contadas, e quais níveis de impacto incluir (Crítico é sempre incluído).
• Somente administradores do projeto podem configurar o limite.

Veja Alterar o Limite de A11y para detalhes completos.

O que significam os níveis de impacto (Crítico, Sério, Moderado, Menor)?

Cada violação de acessibilidade é atribuída a um de quatro níveis de impacto, do mais grave ao menos grave:

• Crítico: Usuários com deficiências estão completamente bloqueados de acessar ou interagir com um recurso.
• Sério: Usuários com deficiências enfrentam barreiras significativas ao interagir com o site.
• Moderado: Algumas barreiras existem, mas o conteúdo básico ainda é acessível.
• Menor: Problemas menos graves que ainda exigem resolução para conformidade total.

Veja o Glossário para definições detalhadas.

Por que os mesmos problemas continuam a ser relatados como novos?

Para decidir se um problema é novo, o Developer Hub compara cada resultado com a execução anterior por regra, seletor de elemento e URL, conforme descrito em Duplicado no glossário. Se o mesmo problema no mesmo elemento for relatado como novo em cada execução, uma dessas coisas está mudando entre as execuções. Há duas causas comuns.

O URL muda entre as execuções. O URL é comparado na íntegra, então um ID de sessão, um carimbo de tempo, um parâmetro de quebra de cache ou qualquer outro valor dinâmico na string de consulta faz com que cada execução pareça uma página diferente, e todos os problemas em um URL que ainda não foi visto são relatados como novos. Nenhuma configuração normaliza URLs antes de serem comparados, então a solução é tornar os URLs que seus testes visitam determinísticos: remova ou corrija os parâmetros voláteis na configuração do seu teste para que a mesma página produza o mesmo URL em cada execução.

Os IDs ou classes do elemento mudam entre as execuções. Frameworks que geram identificadores como #component-a1b2c3d4 ou .form-field-xyz789 em cada renderização mudam o seletor do elemento, de modo que ele não corresponde mais ao elemento registrado anteriormente. Definir a opção de execução ancestry para true corrige isso, porque o seletor de ascendência descreve o elemento por sua posição na árvore DOM e não contém IDs ou classes:

axe: {
  runOptions: {
    ancestry: true
  }
}

Veja Usando Seletores Dinâmicos para a explicação completa, incluindo a configuração em Java e os prós e contras de habilitar ancestry.

Comparações

Cada contagem de "novo problema" ou "problema resolvido" no Developer Hub vem da comparação da verificação atual com uma verificação de linha de base. Qual verificação conta como a linha de base depende de onde você está olhando:

• Comparações entre branches aparece na visualização de Branches. Elas comparam a última verificação do seu branch com a última execução do pipeline no branch padrão. Uma execução do pipeline é uma verificação desencadeada pelo seu pipeline CI/CD, em oposição a uma execução local de uma máquina de desenvolvedor; o Developer Hub sinaliza estas separadamente para que sempre saiba qual verificação do branch padrão é autoritativa. Isso responde à pergunta "o que mudaria se eu fizesse o merge agora?"
• Comparações dentro do mesmo branch aparece na visualização de Commits. Elas comparam a verificação de um commit com a verificação do commit anterior que tem resultados no mesmo branch, o que não é necessariamente o commit imediatamente anterior em seu histórico Git: um commit sem verificação é ignorado. Isso responde "o que este commit específico introduziu ou corrigiu?"

A Ação do GitHub não é um terceiro tipo de comparação. As contagens que ele publica em um pull request são a comparação dentro do branch para o commit atual, não uma comparação com o branch padrão, que é uma fonte comum de confusão, já que um teste de PR é frequentemente esperado para comparar com o branch em que você estaria fazendo o merge.

Consulte Entenda Seus Resultados para a visão completa.

Como posso determinar o que está mudando de uma versão para outra?

A visualização Branches em um projeto Git permite que você acompanhe as mudanças de acessibilidade entre versões usando uma comparação entre branches:

• O último commit escaneado de cada branch é comparado com a execução mais recente do pipeline em sua branch padrão.
• A comparação mostra o número total de problemas, novos problemas introduzidos, problemas resolvidos e quaisquer mudanças no número de estados de página verificados.

Para ver o que mudou em commits individuais dentro de um branch, veja Como vejo o que mudou de commit para commit dentro de uma branch?

Como posso determinar qual será o impacto de um pull request?

Execute sua suíte de testes no branch do pull request para que os resultados apareçam no Axe Developer Hub:

• Na visualização Branches, cada branch não padrão exibe uma comparação entre branches com o branch padrão, mostrando novos problemas introduzidos, problemas resolvidos e a diferença total.
• Se você usa o Ação do GitHub, ele pode publicar automaticamente um comentário no PR com um resumo e um link para os resultados completos.

Para aprofundar o que cada commit no branch mudou, veja Como vejo o que mudou de commit para commit dentro de uma branch?

Como vejo o que mudou de commit para commit dentro de uma branch?

Na visualização de Branches, clique em Ver Commits em qualquer branch para ver seus commits analisados individualmente. Ao contrário das comparações entre branches na visualização de Branches, a visualização de Commits usa comparações dentro do branch:

• Cada commit é comparado ao commit verificado anterior naquela branch, mostrando novos problemas, problemas resolvidos e mudanças nos estados de página.
• Apenas commits onde a suíte de testes foi executada aparecerão.

Para ver como o branch como um todo se compara ao branch padrão, veja Como comparo uma branch com a última execução de CI/CD no branch padrão?

Como comparo uma branch com a última execução de CI/CD no branch padrão?

A visualização Branches realiza automaticamente uma comparação entre branches para cada branch não padrão em relação à última execução do pipeline do branch padrão:

• Isso exige que um administrador de projeto tenha configurado o Axe Watcher para ser executado no branch padrão como uma execução de pipeline.
• A comparação mostra problemas totais, novos problemas, problemas resolvidos e diferenças nos estados de página.

Para ver o que mudou em commits individuais dentro desse branch, veja Como vejo o que mudou de commit para commit dentro de uma branch?

Como obtenho resultados de comparação precisos antes de criar um pull request?

Para a comparação mais precisa entre branches antes de mesclar, mantenha sua branch de feature atualizada com o branch padrão:

1. Mescle o branch padrão no seu branch de função (por exemplo, git merge main) antes de executar sua suíte de testes.
2. Envie o commit de mesclagem para que o Axe Developer Hub possa verificar a branch atualizada.
3. A visualização Branches então comparará sua branch com a última execução do pipeline no branch padrão, mostrando apenas as mudanças de acessibilidade que sua branch realmente introduz.

Se sua branch de feature estiver atrás do branch padrão, a comparação pode apresentar problemas que já foram corrigidos no branch padrão, mas que ainda não foram mesclados na sua branch de feature. Mesclar o branch padrão primeiro elimina esses falsos positivos e reduz surpresas quando o pull request é mesclado.

Por que vejo problemas relatados como novos ou resolvidos quando um conjunto diferente de testes foi executado?

Uma comparação só é significativa quando o mesmo conjunto de testes foi executado em ambos os lados dela:

• Se uma execução visita uma página que a execução de linha de base nunca visitou, cada problema nessa página é relatado como novo porque não há nada com o que compará-lo.
• Se uma execução pula uma página que a linha de base cobriu, os problemas dessa página aparecem como resolvidos, mesmo que ninguém tenha corrigido nada, já que simplesmente não foram testados.
• Duas execuções cobrindo suítes de teste genuinamente diferentes não deveriam ser comparadas; o resultado não dirá nada útil.

Isso não é algo que uma configuração possa corrigir. Veja Melhores Práticas para Comparações Precisas para saber como configurar sua suíte de testes para que as comparações permaneçam significativas.

Melhores Práticas para Comparações Precisas

• Use um projeto por conjunto de testes. Um projeto deve corresponder a uma suíte de teste. Apontar várias suítes para um projeto significa que cada execução é comparada com uma linha de base produzida por um conjunto diferente de testes, e os contadores de novos e resolvidos deixam de significar qualquer coisa.
• Execute o mesmo conjunto de testes todas as vezes. Mudar o que a suíte cobre muda o que a comparação pode lhe informar. Quando a suíte cresce legitimamente, espere um salto único em novos problemas na execução que adiciona a cobertura.
• Configure uma execução de pipeline no seu branch padrão. Comparações entre branches medem um branch contra a última execução de pipeline no branch padrão. Sem ela, não há linha de base nenhuma, e todos os problemas são relatados como novos, que é a versão mais confusa desse sintoma. Configurá-la é uma tarefa do administrador do projeto; veja Informações do Pipeline.

CI/CD

Como posso garantir que nenhum novo problema de acessibilidade seja mesclado no meu código?

Integre o Axe Developer Hub ao seu pipeline de CI/CD para que verificações de acessibilidade sejam executadas automaticamente em cada commit ou pull request:

• Se você usar o GitHub, o Ação do Axe Developer Hub no GitHub pode bloquear PRs que introduzem erros de acessibilidade.
• Para outras plataformas como GitLab ou Bitbucket, use o API de Serviço REST para consultar os resultados e falhar seu pipeline quando problemas forem detectados.
• Você pode ajustar o que conta como uma falha configurando o limite de a11y.

Como integro o Axe Developer Hub ao meu pipeline de CI/CD se eu não usar GitHub?

Você pode usar a API de Serviço REST para integrar com qualquer plataforma de CI/CD:

• O API de Serviço REST permite que você consulte o Axe Developer Hub por resultados após a execução da sua suíte de testes.
• A API retorna a contagem de problemas, novas violações, violações resolvidas e um link para os resultados completos no Developer Hub.
• Você pode usar esta resposta para aprovar ou reprovar seu pipeline no GitLab, Bitbucket, Jenkins ou qualquer outra plataforma.

Gestão de Projetos

Como posso ver as verificações de acessibilidade de outros membros da equipe em um projeto?

Todos os membros do projeto podem ver todos os resultados dentro de um projeto compartilhado assim que forem adicionados:

• Adicione os membros da equipe através da página de configurações de Membros.
• Nos projetos Git, a visualização de Branches exibe resultados agrupados por chave de API, para que você possa ver quem executou cada verificação.

Para detalhes sobre papéis e permissões, veja Configurar Projetos para Uso da Equipe.

Como exporto meus resultados de acessibilidade?

O Centro de Desenvolvedores oferece várias maneiras de exportar seus dados:

• Na visualização de resumo de problemas, clique no botão Exportar Problemas para baixar resultados como CSV ou JSON.
• Para acesso programático, use o API de Serviço REST para consultar resultados para um commit e projeto específicos.

Veja Obtenha Resultados Programaticamente para mais opções.