Usando o Conector Axe DevTools Linter

O Axe DevTools Linter Connector (também conhecido como o Conector) é uma ferramenta de linha de comando para Linux, macOS e Windows. Ele fornece uma interface de linha de comando para verificar seus arquivos, permitindo assim a automação da verificação de acessibilidade. Você pode, por exemplo, usá-lo para scripts e CI/CD (integração contínua e entrega contínua). O Conector precisa enviar seus arquivos para uma instância do Axe Linter Server, seja ele hospedado pela Deque (SaaS) ou por sua organização (localmente ou nas suas instalações), ou você pode verificar os arquivos localmente sem enviar o conteúdo para um servidor utilizando a opção --local (veja Verificação Local abaixo).

Casos de Uso para o Conector

O Conector Axe DevTools pode

• Verifique a acessibilidade como parte das compilações do Jenkins. Para mais informações, veja Usando o Axe DevTools Linter com o Jenkins.
• Verifique seus arquivos e alimente informações sobre defeitos de acessibilidade no SonarQube. Veja Usando o Axe DevTools Linter com o SonarQube para obter informações sobre como configurar isso.
• Seja utilizado em um script de pré-compromisso do GitHub para bloquear commits que contenham erros de acessibilidade. Veja Usando um Gancho de Pré-Commit do Git com o Axe DevTools Linter.
• Proporcionar uma base para verificar seu código quanto a defeitos de acessibilidade para serviços como:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Verificação Local

O Conector permite evitar enviar seus arquivos para um servidor usando verificação local com a opção de linha de comando --local.

• Vantagens da Verificação Local

  • Muito mais rápido do que usar o servidor.
  • Muito menos provável de encontrar problemas de rede ou de carga no servidor. É especialmente eficiente ao verificar um grande número de arquivos.

• Desvantagens da Verificação Local

  • Requer mais recursos da máquina local.
  • Atualizações para o Conector Axe DevTools Linter requerem o download de uma nova versão do Agora e instalação.
  • Sem rastreamento de uso (se você usar uma chave de licença em vez de uma chave de API).

Chaves de Licença em Comparação com Chaves de API

A verificação local requer uma chave de API ou uma chave de licença. Você pode gerenciar suas chaves de API como parte da sua conta Axe (oferecem flexibilidade). No entanto, você deve solicitar uma chave de licença à Help Desk da Deque. Usar a verificação local com chaves de licença não rastreia o uso dos seus usuários (linhas de código verificadas), mas as chaves de licença também não requerem autenticação remota.

Opções de Instalação

Existem duas opções para instalar o Conector do Axe DevTools Linter:

• Configure um registro npm Agora e use a infraestrutura fornecida pelo NodeJS e npm para instalar, executar e atualizar o Conector. Veja Instalando o Conector do Axe DevTools Linter como um pacote npm para mais informações.
• A outra opção é baixar manualmente o binário do Conector para a arquitetura do seu computador e prepará-lo para uso definindo seu bit de execução (Linux e macOS) e excluindo quaisquer atributos de quarentena estendidos (macOS). Veja a página de downloads.

Variáveis de Ambiente

O Conector reconhece as seguintes variáveis de ambiente:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL e AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL define a URL para a instância do seu servidor Axe DevTools Linter. (Você também pode definir a URL do servidor com o -u ou --url opções de linha de comando.) AXE_LINTER_SERVER_PORT especifica a porta pela qual o servidor escuta, geralmente a porta 3000.

Veja Configurando o Axe DevTools Linter para mais informações sobre como configurar seu servidor, e veja Referência Rápida de URL para a URL a ser usada com a versão SaaS do Axe DevTools Linter. (Você não precisa especificar uma porta ao usar a versão SaaS do Axe DevTools Linter.)

O exemplo a seguir mostra como definir variáveis de ambiente para o Axe DevTools Linter em execução em uma máquina local no Linux ou macOS (embora nenhuma variável de ambiente seja necessária aqui porque esses são os valores padrão):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

Alternativamente, no Linux e macOS, você também pode definir as variáveis de ambiente na mesma linha de comando do comando axe-linter-connector. O exemplo abaixo mostra esse uso. (No entanto, como esses são os valores padrão para o servidor e porta, você não precisa configurá-los.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

AXE_SERVICE_URL

A variável de ambiente AXE_SERVICE_URL permite especificar um servidor alternativo para validar sua chave de API. O valor padrão é https://axe.deque.com.

Clientes de nuvem privada têm um servidor de autenticação dedicado em uma URL específica do cliente. Para usar a verificação local, defina AXE_SERVICE_URL para a URL da sua instância de nuvem privada antes de executar o Conector:

export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --local

A URL da sua instância de nuvem privada foi fornecida quando sua instância de nuvem privada foi configurada. Se você não a tiver, entre em contato com Help Desk da Deque.

DEBUG

A variável de ambiente DEBUG permite que você registre informações detalhadas de depuração para diagnosticar falhas na verificação. Defina a variável de ambiente DEBUG para axe-devtools-linter:* para ativar o registro de depuração, como mostrado abaixo:

DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .

Opções de Linha de Comando

Opções Obrigatórias de Linha de Comando

O Axe DevTools Linter Connector requer as seguintes duas opções:

-s, --source diretório-ou-arquivo
Indica um arquivo ou um diretório contendo arquivos para verificar erros de acessibilidade. Subdiretórios também são pesquisados. Para excluir arquivos de serem verificados, veja a opção exclude na seção Arquivo de Configuração.

-d, --destination diretório
O diretório onde o Conector irá escrever o relatório de acessibilidade.

-u, --url URL
Especifica o servidor a ser usado. O padrão é http://localhost. Para usar o servidor SaaS, especifique --url https://axe-linter.deque.com/

Opções Opcionais de Linha de Comando

Várias opções podem ser necessárias, dependendo do servidor ao qual você está se conectando e quais outros recursos ou formatos de relatório deseja usar.

--additional-properties propriedade
Adiciona propriedades extras aos problemas no relatório de acessibilidade para violações encontradas em componentes mapeados personalizados. O único valor atualmente suportado é customName. Quando especificado, cada problema envolvendo um componente mapeado personalizado ganha uma propriedade customName no relatório, cujo valor é o nome da tag do componente personalizado que desencadeou a violação. Problemas de componentes que não fazem parte de um mapeamento personalizado não terão uma propriedade customName.

axe-linter-connector -s . -d . --additional-properties customName

Por exemplo, se <MyButton> for um componente mapeado personalizado e desencadear uma violação de button-name, o problema no relatório será assim:

{
    "engineId": "axe-linter-jsx",
    "ruleId": "button-name (https://dequeuniversity.com/rules/axe/4.11/button-name?application=axe-linter)",
    "customName": "MyButton",
    "severity": "MAJOR",
    "type": "BUG",
    "primaryLocation": {
        "filePath": "/path/to/app.jsx",
        "message": "Buttons must have discernible text",
        "textRange": {
            "startLine": 7,
            "endLine": 7,
            "startColumn": 12,
            "endColumn": 20
        }
    }
}

--api-key chave-api
Especifica a chave de API para autorizar a verificação com a instância SaaS do Axe DevTools Linter ou para usar a verificação local. Veja Obtendo uma Chave de API SaaS do Axe DevTools Linter para mais informações.

--config nome-do-arquivo
Especifica o nome de um arquivo YAML contendo informações de configuração. Você também pode usar esta opção sem um nome de arquivo, e o Axe DevTools Connector seguirá os passos em Ordem de Pesquisa do Arquivo de Configuração para localizar o arquivo de configuração. Para informações sobre o arquivo de configuração, veja Arquivo de Configuração.

--filename nome-do-arquivo
Especifica o nome de um relatório do SonarQube, padrão: axe-linter-report.json

--issue-type tipo
Utilizado para indicar o tipo de problema para o SonarQube, padrão: BUG, valores permitidos: VULNERABILITY, CODE_SMELL, ou BUG

--license-key *chave*
Especifica a chave de licença para uso na autenticação. Contate o Help Desk da Deque para mais informações sobre como obter uma chave de licença. Esta opção também requer a opção --local.

--local
Ativa a verificação local, que utiliza a máquina onde o Axe DevTools Connector está sendo executado para verificar seus arquivos, em vez de enviá-los para um servidor. Requer uma chave de API (--api-key) ou uma chave de licença (--license-key). Veja Verificação Local.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

-R, --reporter *relator*
Especifica o gerador de relatórios a ser usado, padrão: **sonarqube**

--retry-backoff-limit *limite-de-retentiva*
Especifica o tempo **máximo** em milissegundos que o Conector irá aguardar antes de tentar se reconectar ao servidor após um erro. O padrão é 30.000 milissegundos (30 segundos).

--retry-count *retries*
Especifica o número de vezes para tentar reconectar ao servidor após encontrar um erro de conexão. O Conector dobrará o tempo entre as tentativas (começando em 500 milissegundos ou 0,5 segundos) até atingir *limite-de-retentiva* (especificado com --retry-backoff-limit), onde permanecerá até atingir o número específico de tentativas (e falhar) ou conectar-se ao servidor sem erro.

--severity *nível*
Define o nível de severidade para o SonarQube, padrão: MAJOR, valores permitidos: BLOCKER, CRITICAL, MAJOR, MINOR, ou INFO.

Arquivo de Configuração

Você pode usar um arquivo de configuração YAML com a opção --config.

O seguinte mostra um exemplo de arquivo de configuração:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

No exemplo acima, a regra image-alt será ignorada, e o arquivo meta-refresh.html não será verificado. As regras na tag wcag2a serão usadas, conforme especificado na seção tags. (Veja Tags para mais informações.)

O valor exclude permite valores glob (*) e globstar (**), então o seguinte é permitido:

exclude:
  - tmp/**/*.html

O exemplo acima exclui qualquer arquivo HTML no diretório tmp e seus subdiretórios.

Para mais informações sobre as opções de configuração permitidas, veja Configurando o Axe DevTools Linter.

Exemplo de Uso

Para usar o Conector com o servidor SaaS do Axe DevTools Linter, você pode usar a opção --api-key conforme mostrado abaixo:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d  --url https://axe-linter.deque.com/

Para realizar toda a verificação localmente no computador que executa o Axe DevTools Connector, use a opção --local:

axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/