Contexto
A ideia surgiu durante uma grande atualização do site da Feedzai. Não tínhamos uma forma automatizada e repetível de executar verificações básicas de acessibilidade em todas as páginas, comparar versões ou confirmar que uma correção resistia à publicação seguinte.
Os testes manuais continuavam a ser essenciais, mas as extensões de navegador e os scripts pontuais não se adaptavam bem a uma publicação com muitas páginas. Comecei a combinar Playwright e axe-core para executar as mesmas verificações localmente ou em CI e produzir relatórios JSON e HTML mais fáceis de comparar e partilhar.
Processo e decisões
A primeira versão lia o sitemap.xml e auditava cada URL. Mais tarde, acrescentei listas explícitas de URL e exploração na mesma origem, tornando o motor útil para sites e aplicações de página única cujas rotas nem sempre aparecem num sitemap.
À medida que o projeto cresceu, dividi-o em pacotes especializados. A descoberta de URL, a execução do Playwright e do axe e a normalização dos resultados pertencem ao motor central. Um contrato ScanResult estável e tipado serve depois vários adaptadores substituíveis: a CLI, o gerador de relatórios HTML, o painel local e o servidor MCP.
O painel é deliberadamente local. Aceita ligações apenas em loopback, coloca as análises em fila e guarda o histórico em SQLite. Eventos de ciclo de vida tipados permitem que cada interface apresente o progresso sem ficar acoplada ao motor.
Os planos em Markdown tornam o âmbito de uma auditoria legível por pessoas e ferramentas. Já permitem definir alvos e validar metadados de interação; a execução dessas ações de uma história de utilizador continua a ser aperfeiçoada. Também introduzi cedo o pacote MCP, para que agentes de IA pudessem executar as mesmas auditorias através de uma interface de ferramentas definida, em vez de dependerem de uma integração separada.
Acessibilidade e engenharia
As verificações automáticas não conseguem demonstrar que um produto é acessível. Por isso, os relatórios apresentam os problemas encontrados pelo axe-core, em vez de uma pontuação genérica ou uma declaração de conformidade. HTML determinístico e protegido, JSON legível por máquinas e estados de erro explícitos tornam os resultados úteis em fluxos locais e automatizados.
Cada URL tentado conserva o seu próprio resultado. Se uma página não carregar ou não puder ser analisada, a ferramenta regista a falha e continua com os restantes alvos independentes, em vez de descartar toda a auditoria.
Resultado
As auditorias originais ajudaram a equipa da Feedzai a reduzir as violações de acessibilidade, deixando o site publicado com bastante menos problemas do que a primeira versão.
Atualmente, o A11y Page Checker suporta URL individuais, sitemaps e exploração na mesma origem através de uma API TypeScript, CLI, painel local, relatórios JSON e HTML e ferramentas MCP. Destina-se a profissionais de desenvolvimento web, engenharia de sistemas de design e equipas de produto que precisam de auditorias repetíveis em fluxos locais, pipelines de CI ou ferramentas assistidas por IA. O projeto continua em desenvolvimento enquanto estabilizo a API pública e expando os planos de análise baseados em interações.
Aprendizagem
Uma verificação pontual torna-se muito mais valiosa quando uma equipa consegue repeti-la, comparar o resultado e integrá-la na forma como já trabalha.