Solução de Problemas
Problemas comuns e soluções com o Axe Watcher
Watcher Só Suporta Chrome para Testes, Chromium ou Microsoft Edge
Embora o site Axe Developer Hub suporte vários navegadores, o pacote Watcher só suporta Google Chrome para Testes, Chromium ou Microsoft Edge (JavaScript/TypeScript ou Java com Playwright). 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 em vez disso (com JavaScript/TypeScript ou Java com Playwright, você também pode usar o Microsoft Edge).
- Se você usar o navegador Electron do Cypress, receberá um erro. Especifique o navegador como Chrome para Testes, Chromium ou Microsoft Edge ao invocar o Cypress; caso contrário, ele usará o navegador Electron por padrão. Veja Iniciando Navegadores na documentação do Cypress para mais informações.
Se você usar o WebdriverIO ou o WebDriverJS, deverá configurar seu ambiente de teste para usar explicitamente o Chrome para Testes ou o Microsoft Edge. Se você usar o Java Selenium, deverá configurar seu ambiente de teste para usar explicitamente o Chrome para Testes. Veja Usar o Chrome para Testes para etapas de instalação e exemplos de configuração específicos para a plataforma.
Veja Plataformas de Teste Automatizado para mais informações sobre o software compatível 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ê costuma configurar o ID de compilação no seu AxeConfiguration.
Para mais informações sobre o uso de executores de teste paralelo com diferentes plataformas de CI/CD, veja Executando Testes em Paralelo.
Erros de Acessibilidade Duplicados ou Contagem de Novos Problemas Incorreta
Se o seu site usa IDs dinâmicos ou nomes de classes que mudam sempre que a página é atualizada, é provável que você veja erros de acessibilidade duplicados, especialmente problemas marcados como novo quando execuções de teste 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 como true. O exemplo abaixo mostra como definir a opção na sua configuração:
axe: {
runOptions: {
ancestry: true
}
}Veja Usando Seletores Dinâmicos para mais orientações sobre o uso de 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 Axe Developer Hub agora adere às configurações definidas em Configuração do Axe, e execuções de teste criadas por versões do @axe-core/watcher versão 3.18.0 ou anteriores geram sessões que desconheciam as configurações globais na Configuração do Axe. Você deve atualizar seu pacote @axe-core/watcher e refazer seus testes para criar sessões que sigam a Configuração do Axe da sua empresa. Veja Usando Configurações Globais.
Nenhum Estado de Página Capturado Após Mudar para um IFrame Filho
Se seu teste alternar o contexto atual do navegador para um frame filho usando switchToFrame() (WebdriverIO ou WebDriverJS) ou switchTo().frame() (Java Selenium), o Axe Watcher não capturará estados de página para quaisquer ações realizadas enquanto o navegador estiver focado no frame filho. O Axe Watcher só pode analisar o frame de nível superior.
Por exemplo, no WebdriverIO, a chamada click() abaixo não produzirá um estado de página:
await browser.url('https://example.com')
const iframe = await browser.$('iframe')
await browser.switchToFrame(iframe)
// Actions taken in the child frame will not be analyzed
await button.click()Para retomar a captura de estados da página, volte para o frame de nível superior antes de continuar:
// WebdriverIO
await browser.switchToParentFrame()
// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()O Cypress não é afetado por esta limitação.
Estado de Página Extra Gerado por cy.screenshot()
Se você chamar cy.screenshot() nos seus testes do Cypress, o Axe Watcher pode gerar um estado de página extra. Quando o Cypress tira uma captura de tela, ele modifica brevemente o DOM para desativar animações, e o observador do DOM do Axe Watcher pode detectar essa modificação como uma mudança de estado de página. Isso é um comportamento esperado e não afeta a precisão dos seus resultados de acessibilidade.
Tempo de Execução do Método do Controlador Excedido
O Java Watcher atualmente não permite que você altere valores de tempo limite.
(Apenas JavaScript ou TypeScript) Você receberá uma mensagem semelhante ao seguinte se chamadas para o métodos do Controlador (definido na classe base abstrata Controller 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 do que o tempo padrão para completar e excedeu o tempo limite. Você pode alterar o tempo padrão adicionando um objeto timeout à sua configuração:
axe: {
timeout: {
flush: 10000
}
}Esses valores de tempo limite são independentes do framework de teste que você está usando, e talvez você também precise aumentar os valores de tempo limite para esse framework.
Veja Definir Tempos Limites para informações sobre o uso de tempos limite.
Veja Interface Timeouts e timeouts para mais informações. Os valores padrão de tempo limite são mostrados na tabela sob o Interface Timeouts.
Resultados Não Aparecendo
Se você executou sua suíte de testes e nenhum resultado está aparecendo no Axe Developer Hub para um certo projeto, a causa pode ser encontrada entre os motivos nas seções a seguir:
Não Configurar o Axe Watcher
Sua suíte de testes modificada deve chamar o função de configuração apropriado para o seu framework de teste antes de executar seus testes. Se você não configurar o Axe Watcher corretamente, receberá uma mensagem de que precisa configurar o Axe Watcher. Por exemplo, se esquecer de configurar o Axe Watcher com o Cypress, verá esta mensagem ao executar sua suíte 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 a configuração instruções para exemplos de configuração para seu idioma e framework de teste de navegador.
Não Enviando Resultados
Você precisa chamar a função flush() (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 Axe Developer Hub. Normalmente, você chama a função flush() 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 de linha de comando --incognito 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 (os arquivos em cache são mantidos apenas na memória em 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 definir a chave de API e 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 de pilha revelará se ela é inválida ou está 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 o seu problema, por favor envie-nos um email para que possamos ajudar.