Escrever Testes com Selenium
Escrevendo testes de acessibilidade usando Selenium WebDriver com Axe DevTools for Web para Java
Esta configuração do Axe DevTools não se vincula automaticamente a qualquer biblioteca de asserção. Isso permite testes de acessibilidade simples, bem como a personalização completa dos testes e o uso com asserções personalizadas.
Pré-requisitos
Para usar o Axe DevTools Java Selenium e produzir resultados com ele, você deve já ter criado um arquivo de teste com o Axe DevTools e ter sua escolha de Selenium WebDriver importada e inicializada. Caso não tenha concluído esta etapa, primeiro leia este guia sobre como fazer isso.
Executar uma Varredura
Com esta configuração, executar uma varredura básica de acessibilidade requer apenas três linhas de código. No seu arquivo de teste, substitua <URL> pelo endereço web desejado da página que você quer testar. Os resultados da varredura são salvos na variável results
webdriver.get("<URL>");
Results results = axeSelenium.run(axedriver);
webdriver.quit();Usando os Resultados da Varredura
Depois de executar a varredura, você pode querer fazer algo com os resultados. A opção mais simples é imprimir os resultados no console.
System.out.print(results);Você também pode usar os resultados para verificar violações de acessibilidade. A maneira mais simples de fazer isso é com uma declaração assim:
if (!results.violationFree()) {
//do something, like throw an exception
}Para mais informações sobre como utilizar o objeto de resultados para escrever testes personalizados, consulte a página sobre usando os resultados.
Arquivo de Teste Exemplo
Este arquivo de teste funciona com os mesmos blocos de construção abordados em importar e inicializar, bem como o guia de escrita de testes nesta página.
import com.deque.html.axedevtools.selenium.*;
import com.deque.html.axedevtools.selenium.results.*;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class Example {
public static void main(final String[] args) {
AxeSelenium axeselenium = new AxeSelenium();
WebDriver webdriver = new ChromeDriver();
AxeDriver axedriver = new AxeDriver(wd);
webdriver.get("<URL>");
Results results = axeselenium.run(axedriver);
webdriver.quit();
if (!results.violationFree()) {
int violationCount = results.getViolations().size();
System.out.printf("Found %d violations!\n", violationCount);
System.exit(1);
}
System.out.println("No violations found!");
}
}Neste exemplo, são usados o Chrome e o ChromeDriver. Eles podem ser substituídos por qualquer outro driver de navegador do Selenium e navegador. Se este arquivo de teste encontrar algum problema de acessibilidade, ele imprime o número de violações encontradas e sai com o código de status 1 (erro). Para usar este arquivo de teste no seu próprio ambiente, você deverá adicionar um URL à linha
webdriver.get("<URL>");Referência Adicional
Além do uso básico mencionado acima, o Axe DevTools Java Selenium fornece diversos métodos de encadeamento para modificar a forma como a varredura é executada. Esses métodos podem alterar o escopo e o conjunto de regras da varredura para qualquer configuração desejada. Por padrão, a página inteira é verificada quanto a violações de acessibilidade de acordo com as diretrizes WCAG 2.1 nível AA, com as regras de melhores práticas e experimentais desativadas. As configurações desses métodos de encadeamento permanecem no objeto AxeSelenium, e include e exclude adicionam às áreas anteriores cada vez que você os chama, portanto, reutilizar um objeto para uma segunda varredura configurada de forma diferente carrega as configurações da primeira varredura. Crie um novo AxeSelenium para cada varredura configurada de forma diferente.
Escopo
Por padrão, a página inteira é verificada. No entanto, o Axe DevTools suporta a capacidade de verificar porções específicas de uma página com seus métodos de encadeamento de escopo. Esses métodos de escopo modificam eficazmente a "superfície" da página a ser verificada para a(s) área(s) desejada(s) como alvo. Além disso, existe um método para ignorar violações. Este método não reduz a área da varredura; ele ignora violações de uma regra quando essa regra falha em um elemento específico, e o restante da página ainda é verificado como de costume. Todos esses métodos funcionam com base nas áreas de seletores CSS. A área de cada seletor CSS em uma página pode ser determinada usando a ferramenta "inspecionar elemento" das ferramentas de desenvolvedor do seu navegador.
Métodos de Escopo
Como explicado acima, esses métodos mudam efetivamente a área da superfície da página a ser verificada. Existem dois métodos nesta categoria, um método "inclusivo" e um método "exclusivo". Eles podem ser encadeados mutuamente para criar múltiplos enclaves e exclaves de área de verificação.
Delimitação - Incluindo
O método de encadeamento include altera a varredura para executar apenas na área da página especificada pelo(s) seletor(es) CSS passados para ele. Existem várias maneiras de usar o método include: escopo único, escopo múltiplo, escopo composto e escopo com IFrame.
Este método pode ser usado com um único seletor da seguinte maneira:
axeselenium.include("#selector1").run(axedriver);Esta varredura será executada apenas dentro do escopo do seletor 1
Você pode configurar uma varredura com escopos múltiplos:
axeselenium.include("#selector1").include("#selector2").run(axedriver);Esta chamada irá verificar dentro do escopo do seletor 1 e do seletor 2. Eles podem ser separados por vírgula ou declarados em uma chamada include separada.
Escopo composto pode ser realizado com a seguinte sintaxe:
axeselenium.include("#selector1 .selector2").run(axedriver);Este escopo composto resulta em apenas elementos com o seletor 2 dentro do seletor 1 sendo verificados. Isso é configurado ao não separar os seletores por vírgulas.
Para delimitar dentro de um IFrame, um List<String> pode ser passado. O escopo a ser verificado dentro do IFrame é passado como um parâmetro adicional.
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"})).run(axedriver);Esta varredura é executada em elementos dentro do seletor 1, que está dentro do quadro 1.
Delimitar dentro de múltiplos IFrames funciona da mesma forma que a seleção múltipla padrão. Simplesmente chame include novamente.
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#selector1"}))
.include(Arrays.asList(new String[] {"#frame2", "#selector2"})).run(axedriver);Esta varredura é executada apenas dentro do seletor 1 dentro do quadro 1, e do seletor 2 dentro do quadro 2.
Também é possível delimitar dentro de IFrames aninhados:
axeselenium.include(Arrays.asList(new String[] {"#frame1", "#frame2", "#selector1"})).run(axedriver);Esta varredura é executada dentro do escopo do seletor 1 dentro do quadro 2, que está dentro do quadro 1
Delimitação - Excluindo
Além do método de encadeamento include, esta API possui um método exclude. Este método altera a varredura para que apenas os elementos fora do escopo especificado sejam verificados. Sua configuração e uso são idênticos ao método include, portanto, consulte a seção acima para mais detalhes e exemplos de como ele pode ser usado. Um detalhe importante a lembrar é que os métodos include e exclude podem ser encadeados entre si para criar escopos complexos com muito mais simplicidade do que apenas usando include ou exclude.
Este exemplo mostra uma forma de combinar os métodos include e exclude:
axeselenium.include("#selector1").exclude("#selector2").run(axedriver);Esta varredura é executada apenas na parte da página que está dentro do seletor 1 e que não está também dentro do seletor 2.
Delimitação - Ignorando Violações
O método final relacionado ao escopo é o método de ignorar resultados. Este método não altera o escopo geral da varredura; ele ignora as violações de uma regra quando essa regra falha em um elemento específico. Ele funciona passando o target do elemento que você deseja ignorar, conforme aparece nos resultados, junto com a regra que viola. O alvo é escrito da maneira que Java imprime uma lista, com o seletor dentro de colchetes, como em "[.sidebar]". Uma chamada ignoring por regra é suficiente, pois uma correspondência remove toda a entrada da regra. Não o chame duas vezes para a mesma regra: se ambos os alvos corresponderem a elementos com falhas, a varredura lança um IllegalStateException.
axeselenium.ignoring("[.sidebar]", "color-contrast").ignoring("[#branded-content]", "image-alt").run(axedriver);Esta varredura irá ignorar a violação de contraste de cor na barra lateral e a violação de texto alternativo da imagem no conteúdo de marca. Se o alvo corresponder a qualquer elemento que falhe na regra, toda a entrada da regra é removida das violações, incluindo falhas em outros elementos. Veja AxeSelenium.ignoring(String, String) na referência da API.
Regras
Existem três maneiras de modificar sua configuração de regras para cada varredura. Esses métodos diferentes permitem uma granularidade distinta ao selecionar as regras a serem testadas. O método de conjunto de regras menos granular seleciona um conjunto de regras, ou grupo maior de regras baseado nos padrões comuns de acessibilidade. O método de normas de conjunto de regras, um pouco mais granular, também conhecido como tags, seleciona regras com base nas áreas de um padrão de acessibilidade maior em que se enquadram. Por fim, há três opções de configuração com uma regra de cada vez. Juntos, esses métodos de encadeamento permitem ajustar sua varredura para executar precisamente as regras desejadas.
Para informações sobre as regras do axe-core, visite a página de visão geral de conjunto de regras.
Seleção de Conjunto de Regras
Este método seleciona regras por sua associação mais agregada - um conjunto de regras. Um conjunto de regras é uma coleção de todas as regras que pertencem a um padrão de acessibilidade amplamente utilizado na indústria. Conjuntos de regras para WCAG 2.0, 2.1 e 2.2; ADA Section 508; Trusted Tester v5; EN 301 549; e RGAA. Além disso, as regras de melhores práticas podem ser ativadas com uma bandeira booleana.
Conjuntos de regras são frequentemente compostos por várias tags, que são regras agrupadas por distinções mais específicas. Por exemplo, o conjunto de regras wcag2 contém todas as regras marcadas wcag2a como regras do nível A do WCAG 2.0, wcag2aa para regras do nível AA do WCAG 2.0 e wcag2aaa para regras do nível AAA do WCAG 2.0.
Use esta opção quando quiser selecionar um conjunto de regras sem modificações.
axeselenium.forRuleset("wcag2.1").run(axedriver);Esta varredura será executada apenas com regras do WCAG 2.1.
Para ativar regras de melhores práticas, use a segunda forma de forRuleset.
axeselenium.forRuleset("wcag2.1", true).run(axedriver);Seleção de Padrão
O método de cadeia de padrões de acessibilidade, ou tag, permite um pouco mais de granularidade dentro dos conjuntos de regras do axe-core. Para regras baseadas em WCAG, este método permite que você selecione apenas regras marcadas com A simples ou AA duplo. Esta lista detalha os nomes de tags disponíveis e seus padrões correspondentes.
Esta opção é particularmente útil ao testar apenas uma parte específica de um conjunto de regras, por exemplo, apenas as regras de nível A simples do WCAG 2.0.
| Nome da Tag | Padrão de Acessibilidade |
|---|---|
| wcag2a | WCAG 2.0 Nível A |
| wcag2aa | WCAG 2.0 Nível AA |
| wcag2aaa | WCAG 2.0 Nível AAA |
| wcag21a | WCAG 2.1 Nível A |
| wcag21aa | WCAG 2.1 Nível AA |
| wcag21aaa | WCAG 2.1 Nível AAA |
| wcag22a | WCAG 2.2 Nível A |
| wcag22aa | WCAG 2.2 Nível AA |
| wcag22aaa | WCAG 2.2 Nível AAA |
| section508 | Seção 508 |
| EN-301-549 | EN 301 549 |
| RGAAv4 | Versão 4 do RGAA |
| TTv5 | Trusted Tester v5 |
| melhores-práticas | Melhores práticas endossadas pela Deque |
Embora não definidas explicitamente como parte de qualquer padrão de acessibilidade, oferecemos várias regras que chamamos de "melhores práticas". Embora não estritamente necessárias, testar com essas regras ajudará seu site a ser o mais equitativo possível em termos de uso.
Um único padrão pode ser selecionado da seguinte forma:
axeselenium.accordingTo("wcag2a").run(axedriver);Esta varredura será executada apenas com regras marcadas sob o nível A do WCAG 2.0
Além disso, várias tags podem ser especificadas para selecionar múltiplos padrões de acessibilidade:
axeselenium.accordingTo("wcag2a", "section508").run(axedriver);Estas varreduras executarão tanto as regras marcadas sob o nível A do WCAG 2.0 como a Seção 508 do ADA.
Seleção de Regras
Finalmente, você pode alterar seu conjunto de regras por uma única regra. Para informações sobre os nomes de todas as regras do axe-core e o que cada regra testa, veja a documentação de descrições de regras do axe-core.
Esses métodos funcionam bem quando o seu grupo final de regras desejado é diferente de um conjunto de regras existente ou padrão/etiqueta apenas por algumas regras individuais. Para criar um conjunto de regras completamente personalizado, confira nossas opções de regras personalizadas.
Verificação de Regras Adicionais
O método de cadeia de verificação permite que você adicione regras adicionais para testar além do seu conjunto de regras padrão.
Este método pode ser usado para verificar uma única regra adicional:
axeselenium.checking("label").run(axedriver);onde a varredura é executada com o conjunto de regras padrão, além da regra „label“.
Para verificar várias regras adicionais, passe todas em uma chamada. Chamar checking uma segunda vez substitui as regras da primeira chamada em vez de adicioná-las.
axeselenium.checking("label", "tabindex").run(axedriver);onde a varredura é executada com o conjunto de regras padrão, além das regras „label“ e „tabindex“.
Também pode ser usado para adicionar uma única regra ou várias regras a uma tag específica:
axeselenium.accordingTo("wcag2a").checking("tabindex").run(axedriver);onde a varredura é executada testando contra as regras do WCAG 2.0 nível A, com a adição da regra „tabindex“.
Ignorando Regras
Semelhante ao método de verificação, o método de omissão altera as regras padrão a serem usadas pela(s) regra(s) especificada(s). No entanto, em vez de adicioná-las ao conjunto de regras, o método de omissão remove a(s) regra(s) especificada(s) das utilizadas para testar a página. Sua configuração e uso são idênticos ao método de verificação, então consulte a seção acima para mais detalhes e exemplos de como usá-lo.
axeselenium.accordingTo("wcag2a").skipping("label").run(axedriver);Este exemplo mostra uma varredura testando contra regras do WCAG 2.0 nível A, com a remoção da regra "label".
Os métodos de verificação e omissão definem a mesma opção, então apenas a última das duas chamadas em um encadeamento tem efeito. Não os combine na mesma varredura.
Verificação Apenas
O método de verificação apenas verifica apenas a(s) regra(s) especificada(s). Qualquer regra não especificada explicitamente não será incluída na varredura.
Este método de encadeamento pode ser usado para especificar uma única regra:
axeselenium.checkingOnly("tabindex").run(axedriver);onde a varredura é executada apenas com a regra „tabindex“.
Para especificar mais de uma regra, passe todas em uma chamada. Uma segunda chamada checkingOnly substitui as regras da primeira. checkingOnly e accordingTo também definem a mesma opção, então apenas o último dos dois tem efeito.
axeselenium.checkingOnly("label", "tabindex").run(axedriver);onde a varredura é executada apenas com as regras „label“ e „tabindex“.
Desativando iframeTestes
Em páginas voláteis, iframes podem causar problemas. Axe precisa ser injetado em cada frame e configurado da mesma forma em cada um deles. Se iframes forem adicionados ou removidos enquanto AxeSelenium::run está testando sua página, é possível que exceções sejam lançadas ou que ocorra um comportamento inesperado. Como medida de segurança, AxeSelenium expõe um método para desabilitar toda a interação com iframes, AxeSelenium::disableIframeTesting. Quando ativado, o axe-core não será injetado nos iframes da página, nem será executado neles. Apenas a página de nível superior será verificada.
Pode ser usado da seguinte forma:
axeselenium.disableIframeTesting().run(axedriver);O uso deste método não é recomendado. É sempre melhor esperar que sua página se estabilize antes de passá-la para AxeSelenium::run.
Serviço de Uso
Obtenha informações sobre as tendências de uso do Axe DevTools dentro da sua organização
O serviço de uso pode ser configurado por meio de variáveis de ambiente ou métodos em tempo de execução. Quando ambos são usados, os valores nos métodos são utilizados. Nota: nem todos os campos de dados do serviço de uso podem ser definidos por meio de métodos.
Por padrão, o serviço de uso está ativado e os resultados são enviados para https://usage.deque.com. Defina a variável de ambiente AXE_TRACK_USAGE para false para desativá-lo. Se seus eventos de uso não chegarem à Deque, defina a variável de ambiente AXE_METRICS_URL explicitamente.
Variáveis de ambiente
Essas variáveis de ambiente permitem configurar o serviço de uso e alterar as propriedades dos eventos relatados.
| Nome | Tipo | Pode Sobrescrever | Descrição |
|---|---|---|---|
AXE_DISTINCT_ID |
String | — | Um identificador UUID que permanece o mesmo para o usuário logado (a menos que seja regenerado). Em Ruby, essa variável é chamada de DEQUE_DISTINCT_ID. |
AXE_INCLUDE_TEST_RESULTS |
Boolean | — | Defina como true para incluir os resultados completos do axe-core no objeto testResults de cada evento (o padrão é false). Suportado apenas pelo CLI e pelas APIs do Node.js. |
AXE_METRICS_URL |
String | — | A URL do endpoint de uso REST (o padrão é https://usage.deque.com) |
AXE_TRACK_USAGE |
Boolean | — | Defina como false para desativar o relatório do serviço de uso. O relatório está ativado por padrão. |
AXE_ACTOR |
String | — | Defina como human ou automation para substituir a definição de se os eventos registram uma pessoa ou um pipeline automatizado executando os testes. Por padrão, automation é detectado a partir das variáveis de ambiente comuns de CI. Suportado apenas pelo CLI, pelas APIs do Node.js e pela API Ruby. |
AXE_APPLICATION |
String | false | O aplicativo que foi utilizado para verificar erros de acessibilidade |
AXE_DEV_INSTANCE |
Boolean | true | Indica se este evento é resultante das ações de um desenvolvedor de software. Útil para marcar e posteriormente remover eventos registrados durante o desenvolvimento ou teste. |
AXE_DEPARTMENT |
String | true | O departamento do usuário dentro da organização |
AXE_KEYCLOAK_ID |
String | false | O ID Keycloak do usuário |
AXE_LOGGED_IN |
Boolean | false | Registra se o usuário está logado na aplicação em teste |
AXE_ORGANIZATION |
String | true | A organização do usuário. Para que seu uso apareça nos Relatórios Axe, defina isso para o ID da sua organização (entre em contato com a Deque para obtê-lo). |
AXE_SESSION_ID |
String | false | Um UUID identificando a sessão do usuário |
AXE_TEAMS |
String | false | As equipes executando os testes, como um array JSON de objetos { "id": "...", "name": "..." } ou o caminho para um arquivo JSON que contém um. Um valor passado para a opção --set-teams do CLI, o método setTeams das APIs do Node.js ou a cláusula for_teams ou a propriedade de configuração teams da API Ruby tem precedência. Suportado apenas pelo CLI, pelas APIs do Node.js e pela API Ruby. |
AXE_USER_ID |
String | false | A identidade de um usuário específico, como um endereço de e-mail, nome ou ID de login. Os Relatórios Axe contam usuários únicos a partir deste valor. |
AXE_USER_JOB_ROLE |
String | false | O cargo do usuário |
AXE_USER_STATUS |
String | false | Informações de status que você deseja associar ao usuário |
Habilitar Rastreamento
Este método permite que os usuários optem por enviar ou não dados para o serviço de uso. O envio está ativado por padrão.
.enableTracking(boolean state)Definir URL de Rastreamento
Este método permite que os usuários alterem para onde os dados de métricas de uso estão sendo enviados. O padrão é https://usage.deque.com
.setTrackingUrl(String url)Definir ID Distinto
Este método permite que os usuários alterem o ID distinto que está sendo armazenado/usado
.setDistinctId(String distinctId)Próximas Etapas
Depois de escrever testes com o Axe DevTools, leia mais sobre usando resultados para escrever testes personalizados mais detalhados, ou leia sobre usando o repórter para gerar relatórios das varreduras de acessibilidade.
Solução de Problemas
Se você tiver problemas ao configurar seus testes de acessibilidade, entre em contato diretamente com seu representante Deque, fale conosco através do nosso atendimento ao cliente, ou envie-nos um email. Estamos felizes em ajudar a iniciar seus esforços de teste de acessibilidade.
