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. Problemas que você pode encontrar:
- Se você usar o Google Chrome versão 139 ou posterior, receberá um erro do Watcher. Use Chrome para Testes, Chromium ou Microsoft Edge em vez disso.
- 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, o WebDriverJS ou o Java Selenium, deve configurar seu ambiente de teste para usar explicitamente o Chrome para Testes ou o Microsoft Edge. Veja Usar o Chrome para Testes para etapas de instalação e exemplos de configuração específicos da plataforma.
Veja Plataformas de Teste Automatizado para mais informações sobre o software compatível com o Watcher.
Falhas do Microsoft Edge com Java Selenium
Se seus testes de Java Selenium lançarem um IllegalStateException com a mensagem O suporte ao Microsoft Edge requer Selenium 4 ou superior, seu projeto está usando o Selenium 3. O EdgeOptions do Selenium 3 tem como alvo o antigo navegador EdgeHTML, que o Axe Watcher não suporta. Atualize selenium-java para 4.x para testar no Microsoft Edge, ou continue testando no Chrome for Testing ou no Chromium com ChromeOptions e ChromeDriver, que a integração do Selenium Java suporta no Selenium 3.141.59 e versões posteriores.
Sem Resultados do Microsoft Edge com WebdriverIO
Se seus testes WebdriverIO são executados no Microsoft Edge, completam sem nenhum erro, e não produzem resultados no Axe Developer Hub, verifique a versão do seu Watcher. Usar o Microsoft Edge com WebdriverIO requer o Watcher 4.6.0 ou posterior.
Nas versões anteriores, o Watcher enviava suas opções de navegador para a capacidade goog:chromeOptions. O WebDriver do Microsoft Edge as lê de ms:edgeOptions em vez disso, então as opções eram ignoradas e nenhuma análise era realizada. Nada falhou, por isso os testes passaram com um conjunto de resultados vazio. Atualize para 4.6.0 ou posterior para resolver o problema.
A Propriedade args de uma Capacidade do Navegador é Inválida
Se o Watcher relatar que a propriedade args da sua capacidade de navegador de goog:chromeOptions ou ms:edgeOptions deve ser um array de strings, defina args como um array de flags de linha de comando do navegador, ou remova-o:
capabilities: {
browserName: 'MicrosoftEdge',
'ms:edgeOptions': {
args: ['--window-size=1280,720']
}
}Valores como uma string única, um objeto ou um array contendo algo que não seja uma string são rejeitados. O Watcher 4.5.0 e anteriores aceitavam alguns desses valores e falhavam depois com um erro não relacionado.
Problemas de Acessibilidade Dentro de um Iframe de Origem Cruzada Estão Faltando
Se sua análise for bem-sucedida, mas seus resultados não contiverem nada de um <iframe> servido de uma origem diferente da página em teste, esse frame não foi analisado. O Watcher sempre analisa frames de mesma origem, mas analisa um frame de origem cruzada apenas quando você lista a origem desse frame:
- (JavaScript ou TypeScript)
allowedOrigins - (Java)
setAllowedOrigins()
axe: {
allowedOrigins: [ 'https://pay.example.com' ]
}Não inclua a origem do seu próprio aplicativo, que é sempre permitida.
Para confirmar quais origens foram ignoradas, procure o diagnóstico cross_origin_frame_not_allowlisted. Ele é relatado independentemente de você ter definido a opção, nomeia as origens de cruzamento que não foram analisadas e imprime a linha de configuração que você pode colar. Os diagnósticos aparecem apenas na saída de depuração: defina DEBUG=axe-watcher:* ao executar seus testes (JavaScript ou TypeScript), ou configure seu framework de registro para mostrar mensagens DEBUG para o Axe Watcher (Java). Com a integração do Selenium Java, você também pode ativar o registro de depuração com enableDebugLogger().
Se os resultados ainda estiverem faltando após listar a origem:
- O frame tem um atributo
sandboxque omiteallow-same-origin, relatado comocross_origin_frame_unscannable. O frame então tem uma origem opaca que nenhuma entrada em sua lista pode nomear. Adicioneallow-same-originao atributosandbox. - O frame redireciona para longe da origem em seu
src, como um domínio de nível superior redirecionando parawww, ouhttpredirecionando parahttps. Liste a origem em que o frame realmente termina. - O frame está aninhado mais de um nível profundo. Diagnósticos de cobertura são relatados da página de nível superior sobre os frames que ela incorpora diretamente, então um frame profundamente aninhado não é relatado.
Se a análise falhar completamente em vez de reportar menos, procure o diagnóstico cross_origin_frame_timed_out: um frame respondeu ao ping inicial do Watcher, mas não retornou resultados a tempo. Remova essa origem de sua lista ou aumente runOptions.frameWaitTime.
Se o frame for analisado mas seus resultados não refletirem o que seu teste fez dentro dele, a análise automática é a causa. Ela não consegue detectar mudanças feitas dentro de um frame, então um frame permitido é analisado a partir da última alteração na página de nível superior. Chame analyze() você mesmo após interagir com o conteúdo dentro de um frame. Este é um problema separado de Nenhum Estado de Página Capturado Após Mudar para um IFrame Filho, que se aplica quando o contexto do navegador é alternado para dentro do frame.
Veja Analisar iframes de Origem Cruzada para a visão completa.
Origens Rejeitadas por allowedOrigins
Se o Watcher relatar que uma entrada allowedOrigins é inválida, a entrada não é uma origem simples que possa comparar com um frame. Cada entrada precisa de um esquema (http ou https), um host e uma porta opcional, sem mais nada. Causas comuns:
- Um curinga, como
https://*.example.com. Nomeie cada origem explicitamente. - Um caminho, string de consulta, fragmento ou credenciais, como
https://pay.example.com/checkout. - Um esquema ausente, como
pay.example.com. - Um esquema diferente de
httpouhttps. - Um domínio contendo caracteres fora do alfabeto inglês, como
café.example.com. Use a forma punycode em vez disso.
O Watcher rejeita esses casos em vez de ignorá-los, porque uma entrada que não corresponde à verdadeira origem de um frame deixaria o frame não analisado enquanto sua execução de teste ainda relataria sucesso. Veja Analisar iframes de Origem Cruzada.
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 o seu teste alterna o contexto atual do navegador para um frame filho usando switchToFrame() (WebdriverIO ou WebDriverJS) ou switchTo().frame() (Selenium Java), o Axe Watcher não capturará estados de página para quaisquer ações realizadas enquanto o navegador está focado no frame filho. O Axe Watcher captura estados de página apenas enquanto o contexto do navegador está no frame de nível superior.
Esta é uma questão separada de se o iframe conteúdo é analisado. O Watcher analisa frames de mesma origem e frames de origem cruzada cuja origem você lista; veja Analisar iframes de Origem Cruzada.
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.