Referência de API JavaScript para Navegadores do Axe DevTools para Web

Introdução

A API do Axe DevTools foi projetada para ser uma melhoria sobre a geração anterior de APIs de acessibilidade. Ela oferece os seguintes benefícios:

• Funciona em qualquer navegador moderno
• Projetada para trabalhar com a infraestrutura de teste existente
• Funciona localmente; não é necessária conexão com um servidor de terceiros
• Realiza verificação de violações em múltiplos níveis de iframes aninhados
• Fornece uma lista de regras e elementos que passaram na verificação de acessibilidade, assegurando que as regras foram aplicadas a todo o documento

Começando

Esta seção descreve brevemente como usar as APIs do Axe DevTools para analisar o conteúdo de páginas web e retornar um objeto JSON que lista quaisquer violações de acessibilidade encontradas.

A API do Axe DevTools pode ser usada como parte de um processo mais amplo realizado em muitas, senão todas, páginas de um site. A API analisa o conteúdo das páginas web e retorna um objeto JSON que lista quaisquer violações de acessibilidade encontradas. Aqui está como começar:

1. Carregar a página no sistema de teste
2. Opcionalmente, definir opções de configuração para a API JavaScript (AxeDevTools.configure)
3. Chamar a API JavaScript de análise (AxeDevTools.run)
4. Ou fazer asserções contra os resultados ou salvá-los para processamento posterior

Referência de API

Visão geral

As APIs do Axe DevTools são fornecidas no arquivo JavaScript axe-devtools.js. Ele deve ser incluído na página web em teste. Os parâmetros são enviados como parâmetros de função JavaScript. Os resultados são retornados em formato JSON.

Notas da API

• Um teste de Regra é composto por sub-testes. Cada sub-teste é retornado em um array de 'checks'
• O "helpUrl" no objeto de resultados linka para uma descrição mais ampla do problema de acessibilidade e sugestão de correção. Todos os links apontam para as páginas de ajuda da Deque University.

AxeDevTools.init

Propósito

Inicialize a API do Axe DevTools para utilizar um dos conjuntos de regras padrão incorporados.

Descrição

Inicializa o motor do Axe DevTools, substituindo o conjunto de regras padrão e habilitando um dos subconjuntos de regras padrão.

Sinopse

AxeDevTools.init(ruleSetID);

Parâmetros

• ruleSetID - opcional String que identifica o conjunto de regras. Os valores válidos atualmente são:

  • 508
  • en301549
  • rgaav4
  • ttv5
  • wcag2
  • wcag21
  • wcag22
  • wcag2aaa
  • wcag21aaa
  • wcag22aaa

Retorna: indefinido

AxeDevTools.ruleSets

Propósito

Um array das definições do conjunto de regras padrão

Descrição

Fornece acesso direto ao array de definição do conjunto de regras padrão. O array consiste em objetos JavaScript com a seguinte estrutura:

{
  id: String identifier for the rule set,
  defn: Object containing the rule set definition
}

Exemplo Um

Como filtrar o array para encontrar a definição do conjunto de regras dos níveis A e AA do WCAG 2.

var rsets = AxeDevTools.ruleSets;
var wcag2 = rsets.filter(function (item) {
  return item.id === 'wcag2';
})[0].defn;

AxeDevTools.getRules

Objetivo

Obter informações sobre todas as regras no sistema

Descrição

Retorna uma lista de todas as regras com seu ID e descrição.

Sinopse

AxeDevTools.getRules([Tag Name 1, Tag Name 2...]);

Parâmetros

• tags - opcional Array de tags usado para filtrar as regras retornadas. Se omitido, retornará todas as regras.

Retorna: Array de regras que correspondem ao filtro de entrada, com cada entrada tendo um formato de {ruleId: <id>, description: <desc>}

O conjunto atual de tags suportadas está listado na tabela a seguir:

Exemplo 1

Neste exemplo, passamos as tags dos níveis A e AA do WCAG 2 em AxeDevTools.getRules para recuperar apenas essas regras. A chamada da função retorna um array de regras.

Chamada: AxeDevTools.getRules(['wcag2aa', 'wcag2a']);

Dados Retornados:

[
  { ruleId: "area-alt", description: "Checks the <area> elements of image…" },
  { ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
  { ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
  …
]

AxeDevTools.configure

Objetivo

Configurar o formato dos dados usados pelo Axe DevTools. Isso pode ser usado para adicionar novas regras, que devem ser registradas na biblioteca para serem executadas.

Descrição

O usuário especifica o formato da estrutura JSON passada para o callback de AxeDevTools.run.

Sinopse

AxeDevTools.configure({
  branding: {
    brand: String,
    application: String
  },
  reporter: 'option',
  checks: [Object],
  rules: [Object]
});

Parâmetros

• configurationOptions - Objeto de opções onde os pares nome/valor válidos são:
  • branding - misto (opcional) Usado para definir a marca do helpUrls.
    • brand - string (opcional) define a string da marca--padrão: "worldspace"
    • application - string (opcional) define a string da aplicação--padrão: "AxeDevToolsAPI"
  • reporter - Usado para definir o formato de saída que a função AxeDevTools.run passará para a função de callback
    • v1 para usar o formato da versão anterior: AxeDevTools.configure({ reporter: "v1" });
    • v2 para usar o formato da versão atual: AxeDevTools.configure({ reporter: "v2" });
  • checks - Usado para adicionar verificações à lista de verificações usadas por regras ou para substituir as propriedades das verificações existentes.
    • O atributo checks é um array de objetos de verificação.
    • Cada objeto de verificação pode conter os seguintes atributos:
    • id - string (obrigatório). Isso identifica de forma única a verificação. Se a verificação já existir, quaisquer propriedades de verificação fornecidas serão substituídas. As propriedades abaixo marcadas necessário se novo são opcionais quando a verificação é substituída.
    • evaluate - função (necessário se novo). Esta é a função que implementa a funcionalidade da verificação.
    • after - função (opcional). Esta função é chamada para verificações que operam em um nível de página para processar os resultados dos iframes.
    • options - misto (opcional). Este objeto options é passado para a função evaluate e destina-se a ser usado para configurar verificações. É a propriedade mais comum destinada a ser substituída para verificações existentes.
    • matches - string (opcional). Esta string de seletor CSS filtrará os nós passados para a função evaluate.
    • enabled - booleano (opcional, padrão true). Isso indica se a verificação está ativada ou desativada por padrão. As verificações que estão desativadas não são avaliadas, mesmo quando incluídas em uma regra. Substituir isso é uma maneira comum de desativar uma verificação específica em várias regras.
  • rules - Usado para adicionar regras ao conjunto existente de regras ou substituir as propriedades das regras existentes. O atributo rules é um array de objetos rule. Cada objeto rule pode conter os seguintes atributos:
    • id - string (obrigatório). Isso identifica de forma única a regra. Se a regra já existir, ela será substituída com quaisquer atributos fornecidos. Os atributos abaixo que são marcados como obrigatórios são necessários apenas para novas regras.
    • selector - string (opcional, padrão *). Um seletor CSS usado para identificar os elementos passados para a regra para avaliação.
    • excludeHidden - booleano (opcional, padrão true). Isso indica se os elementos ocultos devem ser passados para a regra para avaliação.
    • enabled - booleano (opcional, padrão true). Se a regra está ativada (um atributo comum para substituição).
    • pageLevel - booleano (opcional, padrão false). Isso indica se a página opera apenas quando o escopo é a página inteira. Um exemplo de uma regra assim é a regra ignorar link. Não é recomendado substituir esta propriedade a menos que a implementação também seja alterada.
    • any - array (opcional, padrão []). Esta é a lista de verificações que devem todas passar ou haverá uma violação.
    • all - array (opcional, padrão []). Esta é a lista de verificações que, se alguma falhar, gerará uma violação.
    • none - array (opcional, padrão []). Esta é a lista das verificações que, se nenhuma passar, gerará uma violação.
    • tags - array (opcional, padrão []). Uma lista das tags que classificar a regra. Na prática, você deve fornecer algumas tags válidas ou a avaliação padrão não invocará a regra. A convenção é incluir o padrão (WCAG 2 e/ou seção 508), o nível WCAG 2, o parágrafo da Seção 508 e os critérios de sucesso WCAG 2. As tags são construídas convertendo todas as letras para minúsculas, removendo espaços e pontos e concatenando o resultado. Por exemplo, os critérios de sucesso WCAG 2 A 1.1.1 se tornariam ["wcag2a", "wcag111"]
    • matches - string (opcional, padrão *). Um seletor CSS que excluirá elementos que não o correspondam.

Retorna: Nada

AxeDevTools.reset

Propósito

Redefina a configuração para a configuração padrão.

Descrição

Substitua quaisquer chamadas anteriores para AxeDevTools.configure ou AxeDevTools.reset e redefina a configuração para a configuração padrão.

Sinopse

AxeDevTools.reset();

Parâmetros

Nenhum

Retorna: indefinido

AxeDevTools.run

Propósito

Analise a página carregada atualmente.

Descrição

Executa várias regras contra a página HTML fornecida e retorna a lista de problemas resultantes.

Sinopse

AxeDevTools.run(context, options, callback);

Parâmetros para AxeDevTools.run

• context: (opcional) Define o escopo da análise — a parte do DOM que você gostaria de analisar. Isso tipicamente será o document ou um seletor específico, como nome de classe, ID, seletor, etc.
• options: (opcional) Conjunto de opções passadas para regras ou verificações, modificando-as temporariamente. Isto contrasta com AxeDevTools.configure, que é mais permanente. Veja acima para mais informações
• callback: (opcional) A função callback que recebe null ou um resultado de erro como o primeiro parâmetro, e o objeto de resultados quando a análise foi concluída com sucesso ou undefined se não foi.

Parâmetro context

Por padrão, AxeDevTools.run irá testar o documento inteiro. O objeto context é um parâmetro opcional que especifica qual elemento deve e qual não deve ser testado. Pode ser passado um dos seguintes:

1. Uma referência de elemento que representa a parte do documento que deve ser analisada
   • Exemplo: Para limitar a análise ao elemento <div id="content">: document.getElementById("content")
2. Uma NodeList como a retornada por document.querySelectorAll.
3. Um seletor CSS que seleciona a parte do documento que deve ser analisada. Isto inclui:
   • Um seletor CSS como um nome de classe (por exemplo, .classname)
   • Um seletor CSS como um nome de nó (por exemplo, div)
   • Um seletor CSS de um ID de elemento (por exemplo, #tag)
4. Um objeto de inclusão-exclusão (veja abaixo)

Objetos include e exclude

O objeto de inclusão-exclusão é um objeto JSON com dois atributos: include e exclude. Ou include ou exclude é obrigatório. Se apenas exclude for especificado, include irá assumir o valor padrão de todo o document.

• Um nó, ou
• Um array de arrays de seletores CSS

Na maioria dos casos, os arrays conterão apenas um seletor CSS. Múltiplos seletores CSS são necessários apenas se você quiser incluir ou excluir regiões de uma página que estão dentro de iframes (ou iframes dentro de iframes dentro de iframes). Neste caso, os primeiros n-1 seletores selecionam o(s) iframe(s), e o enésimo seletor seleciona a(s) região(ões) dentro do iframe.

Exemplos de Parâmetro context

1. Incluir o primeiro item na $fixture NodeList, mas excluir seu primeiro filho

   {
     include: $fixture[0],
     exclude: $fixture[0].firstChild
   }

2. Incluir o elemento com o ID fix, mas excluir qualquer div dentro dele

   {
     include: [['#fix']],
     exclude: [['#fix div']]
   }

3. Incluir todo o documento exceto quaisquer estruturas cujo pai contenha a classe exclude1 ou exclude2

   {
     exclude: [['.exclude1'], ['.exclude2']];
   }

Parâmetro options

O parâmetro options é uma forma flexível de configurar como AxeDevTools.run opera. Os diferentes modos de operação são:

• Executar todas as regras correspondentes a um dos padrões de acessibilidade.
• Executar todas as regras definidas no sistema, exceto pela lista de regras especificadas.
• Executar um conjunto específico de regras fornecidas como uma lista de IDs de regra.

Exemplos de Parâmetro options

1. Executar apenas Regras para um padrão de acessibilidade

   Existem certos padrões definidos que podem ser usados para selecionar um conjunto de regras. Os padrões definidos e a string de tag são definidos da seguinte forma:

   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
   TTv5	Tester Confiável v5
   melhor-prática	Melhores práticas endossadas por Deque

   Para executar apenas as regras WCAG 2.0 Nível A, especifique options como:

   {
     runOnly: {
      type: "tag",
      values: ["wcag2a"]
     }
   }

   Para executar tanto as regras WCAG 2.0 Nível A quanto Nível AA, você deve especificar tanto wcag2a quanto wcag2aa:

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a", "wcag2aa"]
     }
   }

2. Executar apenas uma lista especificada de Regras

   Se você deseja executar apenas certas regras, especifique opções como:

   {
     runOnly: {
       type: "rule",
       values: [ "ruleId1", "ruleId2", "ruleId3" ]
     }
   }

   Este exemplo executará apenas as regras com os IDs ruleId1, ruleId2 e ruleId3. Nenhuma outra regra será executada.

3. Executar todas as Regras ativas, exceto uma lista de regras

   A operação padrão para AxeDevTools.run é executar todas as regras WCAG 2.0 Nível A e Nível AA. Se certas regras devem ser desativadas, especifique options como:

   {
     "rules": {
       "color-contrast": { enabled: false },
       "valid-lang": { enabled: false }
     }
   }

   Este exemplo desativará as regras com os IDs color-contrast ou valid-lang. Todas as outras regras serão executadas. A lista de IDs de regras válidos é especificada na seção abaixo.

4. Executar um conjunto modificado de regras usando tags e habilitação de regras

   Um conjunto modificado pode ser definido combinando runOnly com type configurado para as tags desejadas e usando a opção rules. Isso permite incluir regras com tags não especificadas e excluir regras com a tag ou tags especificadas.

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a"]
     },
     "rules": {
       "color-contrast": { enabled: true },
       "valid-lang": { enabled: false }
     }
   }

   Este exemplo inclui todas as regras de nível A, exceto valid-lang, e também incluirá a regra de contraste de cor de nível AA.

5. Executar apenas algumas tags, mas excluir outras

   A opção runOnly pode aceitar um objeto com uma propriedade include e exclude. Apenas os testes que correspondem a uma tag incluída serão executados, exceto aqueles que compartilham uma tag da lista de exclusão.

   {
     runOnly: {
       type: 'tags',
       value: {
         include: ['wcag2a', 'wcag2aa'],
         exclude: ['experimental']
       }
     }
   }

   Este exemplo primeiro inclui todas as regras wcag2a e wcag2aa. Todas as regras marcadas como experimental são então removidas das regras a serem executadas.

Parâmetro callback

O parâmetro callback é uma função que será chamada quando a função assíncrona AxeDevTools.run for concluída. A função callback recebe dois parâmetros. O primeiro parâmetro será um erro lançado dentro do Axe DevTools se AxeDevTools.run não puder ser concluído. Se o Axe DevTools for concluído corretamente, o primeiro parâmetro será nulo, e o segundo parâmetro será o objeto de resultados.

Retornar Promessa

Se o callback não for definido, o Axe DevTools retornará uma promessa em vez disso. No entanto, o Axe DevTools não fornece polyfill para a biblioteca de promessas. Portanto, em sistemas sem suporte para promessas, este recurso não está disponível. Se você não tem certeza se os sistemas nos quais precisará do Axe DevTools têm suporte para promessas, sugerimos que use o callback fornecido por AxeDevTools.run em vez disso.

Resultado error

Isso será null ou um objeto que é uma instância de Error. Se você constantemente receber erros, por favor, relate este problema para a Deque Systems.

Objeto results

A função callback passada como terceiro parâmetro de AxeDevTools.a11yCheck é executada no objeto results. Este objeto possui dois componentes: um array passes e um array violations. O array passes acompanha todos os testes aprovados e informações detalhadas sobre cada teste. Isso leva a um teste mais eficiente, especialmente com teste manual, já que o usuário pode facilmente determinar os testes já aprovados. Da mesma forma, o array violations acompanha todos os testes falhos e informações detalhadas sobre cada um.

url

A URL da página testada.

timestamp

A data e hora em que a análise foi concluída.

Array passes e violations

• description - Uma string de texto que descreve o que a regra faz
• help - Texto de ajuda que descreve o teste realizado
• helpUrl - Uma URL que fornece mais informações sobre os detalhes da violação. Links para uma página no site da Deque University.
• id - Um identificador exclusivo para a regra; veja a lista de regras
• impact - A seriedade da violação. Pode ser um de menor, moderado, grave ou crítico se a regra falhou ou null se o teste foi aprovado.
• tags - Um array de tags atribuídas a esta regra. As tags podem ser usadas no objeto option para selecionar quais regras serão executadas (veja Parâmetro de Opções acima).
• nodes - Um array de todos os elementos que a regra testou
  • html - Um trecho de HTML do elemento
  • impact - A gravidade da violação. Pode ser um de leve, moderado, grave ou crítico se o teste falhou ou null se o teste foi aprovado.
  • target - Um array de seletores onde cada elemento corresponde a um nível de iframe ou frame. Se houver um iframe ou frame, devem existir duas entradas em target. Se houver três níveis de iframe, devem existir quatro entradas em target.
  • any - Um array de verificações onde pelo menos uma deve ter sido aprovada. Cada entrada no array contém:
    • id - Identificador único para esta verificação. Os IDs de verificação podem ser iguais aos IDs de regra.
    • impact - A gravidade da verificação. Pode ser um de leve, moderado, grave ou crítico. Cada verificação que faz parte de uma regra pode ter diferentes impactos. O maior impacto de todas as verificações que falharem é relatado para a regra.
    • message - A descrição do porquê esta verificação foi aprovada ou falhou.
    • data - Informações adicionais e opcionais específicas para o tipo de verificação. Por exemplo, uma verificação de contraste de cores incluiria a cor do primeiro plano, a cor do plano de fundo, a taxa de contraste, etc.
    • relatedNodes - Um array opcional de informações sobre outros nós relacionados com esta verificação. Por exemplo, uma violação de verificação de ID duplicado listaria os outros seletores com o mesmo ID duplicado. Cada entrada no array contém as seguintes informações:
      • target - Um array de seletores para o nó relacionado
      • html - O código-fonte HTML do nó relacionado
  • all - Um array de verificações realizadas onde todas devem ter sido aprovadas. Cada entrada no array contém as mesmas informações que o array any.
  • none - Um array de verificações realizadas onde todas não devem ter sido aprovadas. Cada entrada no array contém as mesmas informações que o array any.

Exemplo Dois

Neste exemplo, passaremos o seletor para o documento inteiro, não passaremos opções, o que significa que todas as regras habilitadas serão executadas, e teremos uma função de callback simples que registra o objeto completo dos resultados no console log:

AxeDevTools.run(document, function (err, results) {
  if (err) throw err;
  console.log(results);
});

array passes

• passes[0] ...

  • help - "Elements must have sufficient color contrast"
  • helpURL - "https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"
  • id - "color-contrast"
    • nodes
    • target[0] - "#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"

• passes[1] ...

No exemplo acima, o array passes contém duas entradas correspondentes às duas regras testadas. O primeiro elemento no array descreve uma verificação de contraste de cores. Os campos help, helpUrl e id são retornados para cada entrada no array passes. O array target possui um elemento com o valor de:

#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop

O elemento selecionado por target[0] foi verificado para a regra de contraste de cores e foi aprovado.

Cada entrada subsequente no array de aprovações tem o mesmo formato, mas detalhará as diferentes regras que foram executadas.

array violations

• violations[0]

  • help - "<button> elements must have alternate text"
  • helpURL - "https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"
  • id - "button-name"
    • nodes
    • target[0]
    • "post_5919997 > .row.content-wrapper > .column > span > iframe" * target[1]
    • "#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"

• violations[1] ...

The violations array contains one entry for a test that checks if buttons have valid alternate text (the button-name rule). This first entry in the array has the help, helpUrl, and id fields.

The target array demonstrates how we specify the selectors when the node specified is inside an iframe or frame. The first element in the target array (target[0]) specifies the selector to the iframe containing the button. The second element in the target array (target[1]) specifies the selector to the actual button but starts from inside the iframe selected in target[0].

Exemplo Três

Neste exemplo, passamos o seletor para o documento inteiro, habilitamos duas regras de melhores práticas adicionais e temos uma função de callback simples que registra o objeto completo dos resultados no console log:

In this example, we pass the selector for the entire document, enable two additional best practice rules, and have a simple callback function that logs the entire results object to the console log:

AxeDevTools.run(
  document,
  {
    rules: {
      'heading-order': { enabled: true },
      'label-title-only': { enabled: true }
    }
  },
  function (err, results) {
    if (err) throw err;
    console.log(results);
  }
);