Testes de acessibilidade automatizados no CI/CD

O defeito de acessibilidade mais barato é aquele que nunca chega ao seu ramo main. Quando uma auditoria periódica revela uma etiqueta de formulário em falta ou uma ordem de foco quebrada, o código responsável já foi lançado, três outras funcionalidades foram construídas por cima dele e talvez já tenha frustrado um utilizador real. A correção é mais difícil, o risco de regressão é mais elevado e o custo — em tempo de engenharia e em confiança — multiplicou-se.

Os testes de acessibilidade automatizados no CI/CD invertem essa economia. Em vez de descobrir os problemas semanas ou meses mais tarde, apanha os que são automatizáveis no momento em que são introduzidos, no próprio pull request que os introduz. Este artigo é um guia prático para equipas de engenharia: como antecipar a acessibilidade, onde colocar as verificações no pipeline, como aplicar gates aos builds sem soterrar os programadores em ruído, como integrar com os principais sistemas de CI e — fundamental — onde a automatização para e o teste humano tem de assumir o controlo.

Porquê antecipar a acessibilidade

«Shift left» significa deslocar as verificações de qualidade para mais cedo no ciclo de desenvolvimento, mais perto do momento em que o código é escrito. O princípio é bem compreendido para a segurança e para os testes funcionais, e a acessibilidade beneficia dele exatamente pelas mesmas razões.

Quando a acessibilidade é tratada como uma atividade de auditoria de fase final, três coisas correm mal. Primeiro, os defeitos acumulam-se: uma única auditoria na altura do lançamento produz uma lista de pendências intimidante, e a equipa prioriza-a face à pressão de entrega — a acessibilidade costuma perder. Segundo, perde-se o contexto; o programador que introduziu há três sprints um botão com ícone sem etiqueta já seguiu em frente, e reconstituir a intenção é lento. Terceiro, as mesmas categorias de problemas reaparecem a cada nova funcionalidade, porque nada no fluxo de trabalho diário as impede.

Colocar as verificações no CI/CD fecha esse ciclo. O retorno chega enquanto o código está fresco e o autor ainda está em contexto. As regressões são bloqueadas antes de se acumularem. E a acessibilidade torna-se um gate de qualidade normal e automatizado — tal como os testes unitários, a verificação de tipos e o linting — em vez de um evento especial que acontece a outros. Se quiser a visão mais ampla de onde estas verificações se encaixam, o nosso panorama da acessibilidade no ciclo de vida do desenvolvimento de software mapeia cada fase, do design ao lançamento.

É também aqui que importa uma expectativa lúcida. Antecipar não significa antecipar tudo. A automatização trata de uma fatia específica e valiosa da conformidade WCAG 2.2. O resto continua a exigir pessoas. Voltaremos a essa fronteira em detalhe.

Verificações em cada pull request

O sítio com maior alavancagem para executar verificações de acessibilidade é o pull request. É aí que os revisores já estão a olhar, onde o diff é pequeno e revisível, e onde bloquear é socialmente aceitável porque ninguém espera que um ramo inacabado seja perfeito.

Uma boa configuração ao nível do PR tem três propriedades:

Rápida. As verificações de PR competem com a capacidade de atenção do programador. Limite-as ao que mudou — as páginas ou componentes tocados pelo diff — em vez de percorrer todo o site a cada push. Uma varredura completa do site pertence a um agendamento, não a cada commit.
No local. Os resultados devem aparecer onde o programador trabalha: como comentário no PR, anotação no ficheiro alterado ou status check com uma ligação para o detalhe. Um resultado enterrado num registo de CI que ninguém abre é um resultado sobre o qual ninguém atua.
Acionável. Cada resultado precisa da regra violada, do elemento encontrado, do critério de sucesso WCAG a que corresponde e, idealmente, de uma sugestão de correção. «Regra button-name do axe-core: este <button> não tem nome acessível» é útil; «erro de acessibilidade» não é.

O scanner da QualiBooth foi concebido para funcionar exatamente neste modo — invocado a partir do seu pipeline via CLI ou API, devolvendo os resultados ao pull request e acompanhando-os em painéis para que a equipa possa ver a dívida de acessibilidade a diminuir ao longo do tempo. Os detalhes de configuração nas diferentes plataformas são abordados no nosso serviço de integração da acessibilidade no CI/CD.

Build gates e limiares

Reportar resultados é necessário, mas não suficiente. Um relatório que não bloqueia nada será, sob a pressão dos prazos, ignorado. Um gate — uma verificação capaz de fazer o build falhar — é o que dá dentes à acessibilidade no pipeline. A arte está em escolher sobre o que aplicar o gate.

A abordagem ingénua é fazer o build falhar a qualquer violação de acessibilidade. Num projeto de raiz, isso pode funcionar. Numa base de código existente com uma lista de problemas conhecidos, é um desastre: a primeira execução falha logo, todos os builds falham para sempre e a equipa desativa a verificação num dia. O gate tem de ser calibrado.

Uma estratégia de limiares viável é assim:

Aplique o gate apenas a novas regressões sérias. Compare a verificação atual com uma baseline (abordada na secção seguinte). Faça o build falhar quando o diff introduzir novas violações num nível de gravidade que escolher — por exemplo, crítico e sério — e deixe passar como avisos os problemas de menor gravidade ou preexistentes.
Diferencie as gravidades. Nem todas as violações são iguais. Uma armadilha de teclado completa justifica uma falha rígida; um conselho menor de boa prática pode ser informativo. Faça corresponder os níveis de impacto das regras ao comportamento do gate para que este reflita o dano real para o utilizador.
Permita exceções delimitadas, de forma deliberada. Por vezes, um problema conhecido está acompanhado e agendado. Suporte um mecanismo de supressão explícito e revisível — anotado e limitado no tempo — em vez de deixar os programadores desativar toda a verificação.

O objetivo é um gate em que a equipa confie. Um gate que falha por boas razões é respeitado; um gate que falha por ruído é contornado. Ajustar os limiares à sua base de código faz parte da construção dessa confiança, e é uma parte central da melhoria de processos de acessibilidade.

Estabelecer uma baseline dos problemas existentes

Quase nenhuma base de código real começa com zero defeitos de acessibilidade. A pergunta prática não é «como não temos problemas?», mas «como deixamos de acrescentar novos enquanto saldamos os antigos?». A baseline é a resposta.

Uma baseline é um instantâneo registado dos problemas de acessibilidade que já existem quando ativa o gate. Cada verificação subsequente é comparada com ela. O gate falha sobre o que é novo em relação à baseline; a lista de pendências existente é reconhecida, mas não bloqueia os builds. Isto permite ativar a aplicação imediatamente sem deter o desenvolvimento.

Algumas práticas mantêm as baselines saudáveis:

Faça da baseline um artefacto acompanhado. Versione-a no repositório ou guarde-a na sua plataforma de acessibilidade para que as suas alterações sejam visíveis e revisíveis, e não silenciosas.
Deixe-a apenas encolher. A baseline deve diminuir à medida que os problemas são corrigidos, nunca crescer para absorver novas violações. Se uma correção remover um problema, regenere a baseline para que reintroduzir o problema mais tarde faça o gate falhar.
Agende um saldar deliberado. A lista de pendências capturada na baseline não desaparece sozinha. Combine o gate com um plano para a saldar — alocação de sprint, um épico dedicado de limpeza ou uma cadência de auditoria recorrente. A nossa explicação sobre auditorias de acessibilidade recorrentes descreve como estruturar esse trabalho contínuo.

A baseline é o que torna realista «ativar o gate hoje» para uma equipa que lança há anos.

Testes de componentes e Storybook

As verificações de PR sobre páginas renderizadas são valiosas, mas apanham os problemas tarde — depois de um componente defeituoso já ter sido composto numa página. Testar ao nível do componente apanha-os na origem, antes de um único erro de nome acessível se propagar por quarenta ecrãs.

Se a sua equipa usa um explorador de componentes como o Storybook, é um banco de ensaio ideal para isto. Cada story renderiza um componente isoladamente, nos seus vários estados, que é precisamente o que um motor de acessibilidade automatizado precisa: um DOM determinístico e focado para avaliar.

Uma configuração típica de teste de componentes:

Execute uma verificação de acessibilidade em cada story. Ferramentas como o addon a11y do Storybook (construído sobre o axe-core) podem analisar cada story automaticamente, e as mesmas verificações podem correr em modo headless no CI, para que as violações de componentes façam o pipeline falhar, e não apenas a interface local.
Cubra os estados, não apenas o predefinido. Renderize e teste o estado desativado, o estado de erro, o estado de carregamento, os estados aberto e fechado. Os erros de acessibilidade adoram os estados limite — uma mensagem de erro sem associação programática, uma janela modal que não retém o foco.
Corrija uma vez, beneficie em todo o lado. Um componente corretamente construído e testado torna-se uma garantia reutilizável. Cada página que o consome herda a correção. É o sítio com maior alavancagem para investir, e combina naturalmente com o conjunto de ferramentas de acessibilidade e o software de análise de acessibilidade mais amplos que a sua equipa já utiliza.

Os testes de componentes não substituem os testes ao nível da página — a composição introduz problemas que nenhum componente isolado consegue revelar, como regiões de referência duplicadas ou uma estrutura geral de cabeçalhos quebrada — mas reduzem drasticamente quantos defeitos chegam à página.

Integrar com o seu sistema de CI

O padrão de integração é o mesmo em todas as plataformas: instalar ou invocar o scanner, executá-lo sobre o alvo (um URL, um artefacto compilado ou stories de componentes), e traduzir o seu código de saída e relatório num êxito/falha de pipeline e num artefacto visível para o programador. Como a QualiBooth integra via CLI e API, encaixa em praticamente qualquer sistema. Eis como os principais diferem na prática.

GitHub Actions

A configuração mais comum. Adicione um workflow despoletado em pull_request, arranque a sua aplicação (ou implante uma preview), execute a CLI de acessibilidade sobre ela e publique os resultados como check run ou comentário de PR. O GitHub Actions torna simples as anotações no local e os status checks obrigatórios, pelo que um gate de acessibilidade em falha pode bloquear a integração através das regras de proteção de ramo. Colocar em cache os binários do navegador e as dependências mantém o job rápido.

GitLab CI

Defina um job accessibility no .gitlab-ci.yml, normalmente numa etapa dedicada após o build. O GitLab pode mostrar os resultados no widget do merge request, e pode guardar o relatório JSON como artefacto do job para download e acompanhamento de tendências. As regras de aprovação de merge request permitem tornar o gate bloqueante.

Jenkins

Num Jenkinsfile, adicione uma etapa que execute o scanner e arquive o relatório. O Jenkins é comum em ambientes empresariais e on-premise, onde importa a capacidade de executar tudo atrás da firewall. Use o plugin de publicação adequado para apresentar os resultados, e faça a etapa falhar perante um código de saída não nulo para bloquear o build.

CircleCI

Adicione um job ao .circleci/config.yml, use um executor com um navegador disponível, e guarde o relatório com store_artifacts. Os workflows do CircleCI permitem executar o job de acessibilidade em paralelo com as outras verificações para que não prolongue o tempo total do pipeline, e pode exigir que passe antes de um job de implantação correr.

Azure DevOps

Adicione uma tarefa ao seu pipeline YAML que execute a CLI, e depois publique o relatório com a tarefa de publicação de artefactos. As políticas de ramo do Azure DevOps podem exigir que a verificação de acessibilidade passe antes de um pull request ser concluído, dando-lhe o mesmo gate rígido das outras plataformas.

Seja qual for o sistema que usar, a estratégia de delimitação correta é constante: verificações rápidas e limitadas às alterações nos pull requests; um percurso mais completo num agendamento noturno ou pré-lançamento. Ajudamos as equipas a montar isto de ponta a ponta como parte da integração da acessibilidade no CI/CD, e aconselhamos as equipas de plataforma que preferem implementá-lo elas próprias.

Reduzir os falsos positivos

Nada destrói mais depressa a confiança de uma equipa num gate de acessibilidade do que os falsos positivos. Se a verificação assinala não-problemas, os programadores aprendem a ignorá-la, a suprimi-la por completo ou a contorná-la — e o gate torna-se teatro. Manter o sinal elevado não é opcional; é o que torna todo o esforço duradouro.

Os motores automatizados são conservadores por conceção e, por vezes, assinalam coisas que não são falhas reais no contexto. Fontes comuns de ruído:

Conteúdo oculto ou ainda não renderizado. Os elementos por trás de um menu fechado ou de uma secção carregada de forma diferida podem ser assinalados fora de contexto. Analise os estados realmente renderizados e após interação.
Componentes personalizados que o motor interpreta mal. Um controlo personalizado corretamente implementado com ARIA adequado pode, ainda assim, disparar uma regra genérica. Estes merecem uma exceção revista e documentada — não uma desativação em bloco.
Temporização dinâmica. Analisar antes de a aplicação ter hidratado produz falhas fantasma. Aguarde um estado estável antes de avaliar.
Incorporações de terceiros. Os problemas dentro de uma iframe que não controla devem ser acompanhados separadamente, para que o seu gate meça a sua qualidade.

As defesas práticas são ajustar o conjunto de regras à sua stack, delimitar as supressões de forma estreita e revisível, analisar estados realistas e aplicar o gate apenas às gravidades que representam dano real para o utilizador. Acertar esta calibração para uma base de código específica é exatamente o tipo de trabalho coberto pela nossa consultoria de acessibilidade.

O limite honesto: a automatização cobre apenas parte do WCAG

Eis a fronteira que cada equipa de engenharia precisa de interiorizar, e que nunca esbateremos: os testes automatizados detetam de forma fiável apenas cerca de 30 a 40 % dos critérios de sucesso WCAG. Os restantes 60 a 70 % exigem juízo humano, e nenhuma engenharia de pipeline altera isso.

A razão é estrutural. A automatização destaca-se nos factos verificáveis por máquina: há texto alternativo nesta imagem? Este texto cumpre o rácio de contraste? Este campo de formulário tem uma etiqueta programática? A marcação dos cabeçalhos está presente? São verificações reais e importantes, e apanhá-las automaticamente em cada PR é genuinamente valioso.

Mas um grande número de requisitos WCAG são semânticos e experienciais, e uma máquina não os consegue avaliar:

O texto alternativo é significativo, ou é "image123.jpg"? Um scanner confirma que o texto alternativo existe; só uma pessoa pode julgar se transmite a informação certa.
A ordem de foco faz sentido para quem navega por teclado, ou está tecnicamente presente mas é ilógica?
A página é realmente utilizável com um leitor de ecrã, de ponta a ponta, para concluir uma tarefa real?
As mensagens de erro ajudam um utilizador confuso a recuperar, ou estão apenas associadas corretamente na marcação?
O conteúdo é compreensível, a linguagem clara, a interação previsível?

São perguntas sobre a experiência humana, e são respondidas pelo teste humano — idealmente por auditorias conduzidas por pessoas com deficiência, que usam tecnologia de apoio diariamente e revelam problemas que nenhuma ferramenta automatizada e nenhum programador com visão alguma vez notaria. Uma auditoria de acessibilidade manual minuciosa continua a ser o alicerce de uma conformidade real.

Por isso, o modelo mental correto é em camadas, e não um ou outro:

A automatização CI/CD impede que os problemas verificáveis por máquina cheguem a ser lançados e protege contra regressões — continuamente, a baixo custo, em cada alteração.
Os testes manuais e com tecnologia de apoio cobrem a maioria experiencial do WCAG que a automatização não consegue alcançar.
As auditorias recorrentes revalidam todo o quadro à medida que o produto evolui, porque a conformidade é um alvo móvel, não um certificado pontual.

Esta estratificação é também o que os regimes do mundo real esperam. Quer a sua obrigação decorra da European Accessibility Act, da ADA ou da Section 508, a conformidade é medida face à norma completa — e não face à fatia que um scanner por acaso cobre. Um pipeline verde é necessário, mas não suficiente.

Mais uma coisa a deixar explícita: os overlays de acessibilidade — os widgets JavaScript que prometem conformidade instantânea — não substituem nenhuma das camadas acima, e a QualiBooth não os subscreve. Não corrigem o código subjacente, interferem frequentemente com as próprias tecnologias de apoio de que os utilizadores dependem, e não fazem nada pelos critérios experienciais que mais importam. A verdadeira acessibilidade vem de a construir no produto, que é exatamente o que a integração CI/CD mais o teste humano oferecem.

Juntar tudo

Um pipeline de acessibilidade maduro não é uma única ferramenta nem uma única regra — é um conjunto de camadas que fazem, cada uma, aquilo em que são boas:

As verificações ao nível do componente (por exemplo, no Storybook) apanham os defeitos na origem.
As verificações ao nível do PR dão retorno rápido, no local e acionável em cada alteração, limitado ao diff.
Os build gates com baselines bloqueiam novas regressões sérias sem deter o trabalho sobre problemas herdados.
As varreduras completas agendadas apanham problemas ao nível da composição e acompanham toda a base de código ao longo do tempo.
Os painéis de tendências transformam a saída bruta do CI numa imagem clara da dívida e do progresso.
As auditorias humanas cobrem os 60 a 70 % do WCAG que a automatização estruturalmente não consegue alcançar.

Comece em pequeno. Acrescente uma única verificação de PR nas páginas ou componentes que mais importam, estabeleça uma baseline dos problemas existentes para que o gate esteja verde logo no primeiro dia, e avance a partir daí. O objetivo é um fluxo de trabalho onde as regressões de acessibilidade se tornam tão difíceis de integrar como testes unitários em falha, e onde os problemas que a automatização não consegue apanhar são encaminhados para as pessoas que conseguem.

Se quiser ajuda a conceber ou implementar esse pipeline, o nosso serviço de integração da acessibilidade no CI/CD faz exatamente isto — e pode ver o motor de análise por trás dele numa análise gratuita ou numa demonstração ao vivo.

Perguntas frequentes

Os testes de acessibilidade automatizados substituem as auditorias manuais?

Não, e qualquer fornecedor que afirme o contrário está a induzi-lo em erro. As verificações automatizadas apanham de forma fiável apenas cerca de 30 a 40 % dos critérios de sucesso WCAG — os verificáveis por máquina. A maioria experiencial, como saber se um texto alternativo é significativo ou se um utilizador de leitor de ecrã consegue concluir uma tarefa, exige o teste humano. A automatização CI/CD previne regressões e apanha cedo os problemas fáceis; não certifica a conformidade por si só.

As verificações de acessibilidade não vão atrasar os nossos builds?

Não, se estiverem corretamente delimitadas. Execute verificações rápidas e limitadas às alterações nos pull requests e reserve os percursos completos do site para um agendamento noturno ou pré-lançamento. Os jobs de acessibilidade também podem correr em paralelo com as suas outras verificações de CI, pelo que acrescentam pouco ao tempo total do pipeline. Colocar em cache os binários do navegador e as dependências mantém baixo o custo por execução.

Como evitamos que o gate falhe sobre a nossa lista de pendências existente?

Estabeleça uma baseline. Registe um instantâneo dos problemas que existem quando ativa o gate e configure-o para falhar apenas sobre novas violações relativas a essa baseline. A sua lista de pendências existente é reconhecida e acompanhada, mas não bloqueia os builds, pelo que pode ativar a aplicação imediatamente e saldar a lista segundo um calendário deliberado.

Com que sistemas de CI é que isto se integra?

Os mais comuns — GitHub Actions, GitLab CI, Jenkins, CircleCI e Azure DevOps — e, na prática, qualquer outro, porque a QualiBooth integra via CLI e API. O padrão é o mesmo em todo o lado: executar o scanner, traduzir o seu código de saída em êxito/falha, e fazer surgir o relatório onde os programadores o veem.

Por onde devemos começar?

Acrescente uma verificação ao nível do PR nas suas páginas de maior tráfego ou na sua biblioteca de componentes partilhados, estabeleça uma baseline dos problemas atuais, aplique o gate apenas a novas regressões sérias, e expanda a partir daí. Combine-a desde o início com um plano de teste manual, já que a automatização cobre apenas parte da norma. Se preferir não a construir sozinho, fale com um especialista sobre a sua implementação no seu pipeline, ou compare opções na nossa página de preços.