Escolhendo a Configuração Certa do Axe DevTools Linter

O Axe DevTools Linter pode ser utilizado de várias maneiras, e a combinação certa depende de como sua equipe escreve, revisa e entrega o código. Este guia aborda as principais decisões para que você possa escolher uma configuração que se adeque às suas circunstâncias. A maioria das equipes combina várias dessas opções em vez de escolher apenas uma.

As decisões se dividem em quatro áreas:

1. Onde ocorre a análise (se os arquivos são analisados localmente ou em um servidor, e qual modelo de implantação hospeda esse servidor)
2. Onde o linting acontece no seu fluxo de trabalho (IDE, hook de pré-commit, CI/CD)
3. Se você precisa configurar bibliotecas de componentes
4. Quando adicionar outras integrações como SonarQube

1. Escolha Onde a Análise Ocorre

Há duas escolhas relacionadas aqui: se seus arquivos são analisados em sua própria máquina ou enviados para um servidor, e, se um servidor estiver envolvido, que tipo de servidor os hospeda.

Linting Local ou Baseado em Servidor

Onde seus arquivos são analisados, e se seus conteúdos deixam sua máquina, depende da integração. As três famílias de integrações se comportam de maneira diferente:

• Integrações de IDE sempre fazem lint localmente. A extensão VS Code e o plugin JetBrains analisam arquivos em sua própria máquina com um componente embutido, então o conteúdo dos arquivos nunca sai do seu computador. Eles não requerem chave de API ou de licença para fazer o lint.
• O Conector pode fazer lint de ambas as maneiras. Por padrão, o Conector envia arquivos para um servidor Axe DevTools Linter, mas sua opção --local analisa-os em sua máquina, assim o conteúdo nunca a deixa. A Deque recomenda linting local para a maioria dos casos: é significativamente mais rápido e menos propenso a problemas de rede, especialmente ao fazer lint de um grande número de arquivos. De qualquer forma que opte por fazer lint, o Conector autentica conforme descrito em autenticação do Conector abaixo.
• A Ação do GitHub é sempre baseada em servidor. A Ação do GitHub envia arquivos alterados para um servidor Axe DevTools Linter para análise. Não possui modo de lint local, então esta opção sempre envia o conteúdo dos arquivos para o servidor.

Autenticação do Conector

Quando você usa o Conector, você autentica com uma de duas credenciais, seja fazendo lint localmente ou em relação a um servidor:

• Chave de API (a opção --api-key): Você gerencia as chaves de API por conta própria como parte de sua Conta Axe. O Conector entra em contato com um servidor remoto para validar a chave e relatar o uso (as linhas de código onde foi feito lint). Isso ocorre mesmo quando você faz lint localmente.
• Chave de licença (a opção --license-key): Você solicita uma chave de licença ao Help Desk da Deque. Ela autentica sem atividade de rede e não rastreia uso, o que a torna a escolha certa para redes isoladas ou ambientes com regras estritas de saída. Está disponível apenas com linting local.

Isso dá ao Conector três modos de operação:

As integrações IDE não precisam de credenciais para lint. A Ação do GitHub se autentica com uma chave de API; seu guia de configuração abrange o fluxo de trabalho tanto para servidores SaaS quanto locais.

Modelo de Implantação do Servidor

Se você faz lint em um servidor, ou autentica com uma chave de API enquanto faz lint localmente, você também escolhe qual tipo de servidor hospeda o Axe DevTools Linter. Isso afeta o esforço de configuração, se seus arquivos saem ou não da sua rede e como você autentica.

Escolha SaaS para o início mais rápido e sem infraestrutura para manter. Escolha local quando a política exigir que o código-fonte permaneça dentro da sua rede, ou quando você quiser controle total sobre o servidor. Escolha nuvem privada quando quiser uma instância dedicada gerenciada pela Deque sem operar o servidor você mesmo.

2. Escolha Onde o Linting Ocorre em Seu Fluxo de Trabalho

O feedback de acessibilidade é mais útil quando é recebida cedo e frequentemente. As integrações abaixo se aplicam em diferentes pontos do ciclo de desenvolvimento, e funcionam bem em conjunto: detecte problemas enquanto você digita, novamente antes de um commit, e mais uma vez no pull request.

Uma abordagem comum e em camadas é:

1. Extensão IDE para que os desenvolvedores vejam os problemas imediatamente enquanto escrevem o código.
2. Hook pré-commit ou Ação do GitHub como uma barreira para que os problemas sejam detectados antes ou durante a revisão de código.
3. Conector em CI/CD para impor verificações em todo o código e alimentar outros sistemas.

Não é necessário adotar todas as três camadas de uma vez. As equipes geralmente começam com a extensão IDE e depois adicionam uma verificação de pull request quando estão prontas para impor padrões em toda a equipe.

3. Decida se deseja configurar bibliotecas de componentes

Por padrão, o Axe DevTools Linter verifica elementos HTML padrão e marcações de estrutura. Se o seu código usar componentes personalizados (por exemplo, um <custom-image> que renderiza um <img>), o linter não poderá verificá-los para acessibilidade até que você informe como cada componente se relaciona com um elemento padrão.

Você deve configurar a verificação de componentes se:

• Seu código depende de um sistema de design ou biblioteca de componentes personalizados, e
• Você deseja que problemas de acessibilidade dentro desses componentes sejam sinalizados.

Existem dois caminhos:

• Bibliotecas de componentes preconfiguradas: Se você usa Cauldron React, Material UI (@mui/material) ou React Native, o suporte já está incorporado. Veja Bibliotecas de Componentes Preconfiguradas.
• Mapeamentos personalizados: Para seus próprios componentes, crie mapeamentos em sua configuração. Veja Verificação de Componentes Personalizados para uma visão geral, depois o passo a passo de VS Code e JetBrains ou o Ponto de extremidade REST.

As opções de configuração são compartilhadas entre as integrações do IDE, o Conector e a API REST, e estão documentadas em Configurando o Axe DevTools Linter.

4. Decida Quando Adicionar Outras Integrações

As integrações em passo 2 cobrem as necessidades da maioria das equipes. Considere as seguintes integrações adicionais quando elas corresponderem às ferramentas que você já usa:

Essas integrações são todas construídas sobre o Conector, que produz os resultados de linting que cada sistema consome. A regra geral: opte por outra integração quando ela permitir que os achados de acessibilidade apareçam em uma ferramenta na qual sua equipe já confia, em vez de adicionar uma nova ferramenta por conta própria.

Colocando Tudo Junto

Uma configuração típica para uma equipe usando SaaS pode ser:

• O Extensão do VS Code (ou Plugin JetBrains) para cada desenvolvedor, para feedback enquanto codifica.
• A Ação do GitHub em pull requests, para que os problemas de acessibilidade sejam visíveis durante a revisão de código.
• Mapeamentos de componentes personalizados se a equipe usar um sistema de design.
• integração SonarQube apenas se a equipe já centraliza a qualidade do código lá.

Uma equipe com requisitos mais rigorosos de manuseio de dados pode substituir o SaaS pelo modelo de implantação local e usar o Conector com --local em seu pipeline de CI/CD para que o código-fonte nunca saia de sua rede.

Se você não tem certeza de qual combinação se adapta às suas circunstâncias, entre em contato com a central de ajuda da Deque.