Solução de Problemas

Watcher Suporta Apenas Chrome para Testes ou Chromium

Embora o site do axe Developer Hub suporte vários navegadores, o pacote Watcher suporta apenas Google Chrome para Testes ou Chromium. Problemas que você pode encontrar:

• Se você usar a versão 139 ou posterior do Chrome, receberá um erro do Watcher. Use o Chrome para Testes ou o Chromium.
• Se você usar o navegador Electron do Cypress, receberá um erro. Especifique o navegador como Chrome para Testes ou Chromium ao invocar o Cypress; caso contrário, ele usará por padrão o navegador Electron. Veja Iniciando Navegadores na documentação do Cypress para mais informações.

Se você usar WebdriverIO, WebDriverJS ou Java Selenium, deve configurar seu ambiente de testes para usar explicitamente o Chrome para Testes. Veja Usar o Chrome para Testes para passos de instalação e exemplos de configuração específicos de cada plataforma.

Veja Plataformas de Teste Automatizado para mais informações sobre softwares suportados com o Watcher.

Resultados Incompletos

Se sua suíte de testes usa múltiplos test runners que executam em paralelo e usam o mesmo ID de build não-nulo, os resultados de cada test runner substituirão os de outros test runners para o mesmo SHA do commit Git, dando resultados incompletos. Você deve garantir que cada test runner use o mesmo ID de build não-nulo.

Você geralmente define o ID de build no seu AxeConfiguration.

Para mais informações sobre o uso de test runners em paralelo com diferentes plataformas CI/CD, veja Executando Testes em Paralelo.

Erros de Acessibilidade Duplicados ou Contagem de Novos Problemas Incorreta

Se o seu website usa IDs dinâmicos ou nomes de classe que mudam sempre que a página é atualizada, é provável que você veja erros de acessibilidade duplicados, especialmente problemas marcados como novo quando testes anteriores exibem o mesmo problema no mesmo elemento. (O axe Developer Hub usa IDs e classes para identificar o mesmo elemento entre execuções de teste.) Para resolver este problema, você deve definir a propriedade ancestry no objeto runOptions na sua configuração para true. O exemplo abaixo mostra como configurar a opção na sua configuração:

axe: {
  runOptions: {
    ancestry: true
  }
}

Veja Usando Seletores Dinâmicos para mais orientações sobre como usar seletores dinâmicos.

Veja (JavaScript/TypeScript) runOptions ou (Java) AxeWatcherOptions.setRunOptions() para mais informações.

Versão Antiga de @axe-core/watcher

Se você estiver usando a versão 3.18.0 ou mais antiga do @axe-core/watcher, você receberá esta mensagem de aviso:

O Hub de Desenvolvedores Axe agora adere às configurações definidas em Configuração axe, e execuções de teste criadas por versões do @axe-core/watcher 3.18.0 ou mais antigas geram sessões que desconheciam as configurações globais na Configuração axe. Você deve atualizar o seu pacote @axe-core/watcher e refazer seus testes para criar sessões que sigam a Configuração axe da sua empresa. Consulte Usando Configurações Globais.

Tempo de Execução do Método do Controlador Excedido

(Apenas JavaScript ou TypeScript) Você receberá uma mensagem semelhante à seguinte se chamadas para os métodos do Controlador (definidos na Controller classe base abstrata como analyze(), flush(), start(), e stop()) ou comandos personalizados do Cypress excederem o tempo limite:

Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/wa-troubleshooting for more troubleshooting.

O método especificado Controller (aqui, o método flush()) exigiu mais tempo que o padrão para ser concluído e seu tempo limite foi excedido. Você pode alterar o tempo padrão adicionando um timeout objeto à sua configuração:

axe: {
  timeout: {
    flush: 10000
  }
}

Consulte Definir Tempos Limites para informações sobre como usar tempos limites.

Veja Timeouts Interface e timeouts para mais informações. Os valores padrão de tempo limite são mostrados na tabela sob a Timeouts Interface.

Resultados Não Aparecendo

Se você executou seu conjunto de testes e nenhum resultado está aparecendo no Hub de Desenvolvedores axe para um determinado projeto, a causa pode ser encontrada entre os motivos nas seções a seguir:

Não Configurando o axe Watcher

Seu conjunto de testes modificado deve chamar a função de configuração apropriada para o seu framework de teste antes de executar seus testes. Se você não configurar o axe Watcher corretamente, receberá uma mensagem informando que precisa configurar o axe Watcher. Por exemplo, se você esquecer de configurar o axe Watcher com o Cypress, verá esta mensagem ao executar seu conjunto de testes:

Cypress is not configured for axe Watcher. Please ensure that axe Watcher's cypressConfig() is invoked within Cypress's defineConfig() in your cypress.config.js. All tests will fail with this error.

Consulte as instruções de configuração para exemplos de configuração para sua linguagem e framework de teste no navegador.

Não Enviando Resultados

Você precisa chamar a flush() função (ou o comando personalizado axeWatcherFlush() no Cypress) para enviar os resultados coletados de volta aos servidores da Deque para que os resultados possam ser apresentados no site do Hub de Desenvolvedores axe. Normalmente, você chama a flush() função no hook de limpeza da sua plataforma de automação.

Por exemplo, no arquivo support/e2e.js no Cypress, você adiciona a chamada para afterEach():

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Usando a Opção --incognito

Você não pode usar a opção --incognito da linha de comando com o Chrome; caso contrário, seus testes falharão silenciosamente. Se você estiver usando o modo incógnito para evitar gravar arquivos em cache no disco (arquivos em cache são mantidos somente na memória no modo incógnito), use os métodos de cache da sua suíte de testes.

Não Configurar as Variáveis de Ambiente Necessárias

Se você estiver experimentando com os exemplos no repositório watcher-examples no GitHub, note que os exemplos usam variáveis de ambiente para configurar a chave de API e o ID do projeto, API_KEY e PROJECT_ID.

Teste Executando Muito Rápido

Seus testes podem ser executados rapidamente demais, descarregando a página e liberando seus recursos antes que o Watcher consiga analisá-la. Para resolver esse problema, você pode adicionar um atraso ao final do teste para permitir tempo para analisar a página.

Por exemplo, no Cypress, você pode adicionar um atraso de 10 segundos (10.000 milissegundos) com o método cy.wait() :

describe('Visitor', () => {
  it('should visit example.com', () => {
    cy.visit('https://www.example.com')
    cy.wait(10000);  })
})

Chave de API Ausente ou Inválida

Uma chave de API inválida ou ausente aparece como um arquivo de configuração inválido no Cypress. O rastreamento da pilha revelará se está inválida ou ausente. Uma chave **ausente** resulta no seguinte:

AssertionError [ERR_ASSERTION]: API key is required
    at validateApiKey ...

(Muitas linhas do rastreamento da pilha foram deletadas por brevidade.)

Uma chave **inválida** resulta no seguinte rastreamento de pilha (encurtado):

Error: Server responded to https://axe.deque.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
    at Response.getBody
...

Ajuda

Se você não conseguir resolver seu problema, por favor envie-nos um email para que possamos ajudar.