Ferramenta de Análise

A ferramenta analyze realiza uma análise abrangente de acessibilidade em páginas web, executando uma varredura através da extensão Axe DevTools Browser em um ambiente de navegador real. Funciona perfeitamente com URLs de desenvolvimento local (por exemplo, localhost:3000) e URLs de produção remota.

O Que Ela Faz

1. Autenticação - Valida as credenciais do usuário (seja uma chave de API ou um token de acesso OAuth 2.0) para garantir acesso autorizado
2. Recuperação de Configuração - Obtém as configurações específicas da organização do usuário, incluindo Configuração Axe:
   • Padrão de Teste de Acessibilidade (por exemplo, WCAG 2.2 AA)
   • versão do axe-core
   • Precisa de revisão / melhores práticas
   • Regras Avançadas pré-definido
3. Análise Baseada em Navegador - Inicia uma instância do navegador em segundo plano com a extensão Axe DevTools montada
4. Navegação de Página - Navega até o URL fornecido pelo usuário no seu prompt para o agente AI
5. Varredura de Acessibilidade - Executa uma análise completa de acessibilidade na página renderizado usando a extensão Axe DevTools Browser, garantindo que a experiência real do usuário seja testada (e não apenas o HTML estático)
6. Entrega de Resultados - Retorna resultados de análise abrangentes de volta ao agente em um formato estruturado

Teste Responsivo

A ferramenta analyze suporta parâmetros opcionais viewportWidth e viewportHeight, permitindo testar páginas em dimensões específicas de viewport. Isto é útil para identificar problemas de acessibilidade que só aparecem em certos tamanhos de tela, como pontos de interrupção de dispositivos móveis ou tablets.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Quando ambos os parâmetros são omitidos, a varredura é executada em 1000×1080. Passar apenas viewportWidth define a altura padrão para 1080; viewportHeight requer que viewportWidth seja configurado. Qualquer dimensão pode ter até 7680 pixels.

Varreduras de Página Parcial

Por padrão, a ferramenta analyze escaneia a página inteira. Para delimitar a varredura para uma região específica, passe o parâmetro opcional selector — útil para focar em um único componente ou excluir partes ruidosas e não relacionadas da página dos resultados.

• Uma única string seletora CSS mira em um elemento no frame superior:

  {
    "url": "http://localhost:3000",
    "selector": "#main"
  }

• Um array de seletores CSS passa por limites de iframe ou shadow-DOM — cada segmento seleciona o anfitrião para o próximo. Use um array apenas quando o alvo estiver dentro de um iframe ou shadow root:

  {
    "url": "http://localhost:3000",
    "selector": ["iframe#checkout", "#payment-form"]
  }

Um array suporta até 10 segmentos. Se o seletor não corresponder a nenhum elemento na página, a varredura retorna um erro. Quando selector é omitido, a página inteira é escaneada.

Instrua seu agente AI em linguagem natural — o agente traduz sua intenção na chamada da ferramenta:

Scan only the #main region of http://localhost:3000 for accessibility issues

Interações de Navegador Antes da Varredura

A ferramenta analyze suporta uma matriz opcional before de etapas de interação que são executadas após o carregamento da página mas antes da varredura de acessibilidade. Isto desbloqueia vários cenários de teste do mundo real:

• Páginas protegidas por login — preencha as credenciais e envie antes de varrer a página pós-login
• Banners de cookies/consentimento — dispense banners que de outra forma sobreporiam ou obscureceriam o conteúdo da página
• Conteúdo dinâmico — aguarde até que o conteúdo renderizado pelo cliente (mudanças de rota, DOM injetado tardiamente) apareça antes de escanear

As etapas são executadas na ordem do array, no mesmo contexto do navegador da varredura, então cookies, localStorage e quaisquer mudanças de rota acionadas por click ou fill persistem na varredura.

O array before suporta até 20 etapas. Cada etapa tem seu próprio tempo limite de BROWSER_TIMEOUT_MS (padrão 30000 ms); não há substituição de tempo por etapa.

Ações Suportadas

Exemplo: Fazendo login antes de escanear

Instrua seu agente AI em linguagem natural — o agente traduz sua intenção na chamada da ferramenta:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

O agente resolve o prompt e chama a ferramenta analyze com um payload semelhante a:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}

Injeção de Cookie

A ferramenta analyze suporta um array opcional cookies que define cookies no contexto do navegador antes da navegação — para que eles acompanhem a primeira solicitação para a página. Isso é distinto de ações before, que roda após a navegação e, portanto, não pode influenciar como a solicitação inicial é roteada. Dois usos comuns:

• Roteamento de ambiente — define um cookie de seletor de branch de staging ou feature que uma camada de edge ou CDN lê para decidir qual versão do site servir.
• Sessões pré-autenticadas — injeta um cookie de sessão válido para que a varredura comece já autenticada, sem precisar passar por um formulário de login via before.

O array de cookies suporta até 20 cookies.

Campos do cookie

Exemplo: Acessando uma página pré-autenticada

Instrua seu agente AI em linguagem natural — o agente traduz sua intenção na chamada da ferramenta:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

O agente resolve o valor do cookie e chama a ferramenta analyze com um payload semelhante a:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}

Capturas de tela

A ferramenta analyze pode retornar uma captura de tela da página junto com o relatório de violações, para que você possa ver o que foi analisado. Passe o parâmetro opcional screenshot para optar por isso — um objeto vazio é suficiente:

{
  "url": "http://localhost:3000",
  "screenshot": {}
}

PNG é o padrão. Defina format para "jpeg" para uma imagem menor em páginas pesadas de fotos:

{
  "url": "http://localhost:3000",
  "screenshot": { "format": "jpeg" }
}

A imagem é retornada como um bloco de conteúdo de imagem padrão MCP, após o relatório de violações.

O que a captura de tela mostra

• O viewport visível, não a página inteira. Conteúdo abaixo da dobra não está incluído. Para capturar mais da página, passe um viewportHeight alto (ex.: 4096) para que a área visível cubra o que você deseja ver.
• A página como estava imediatamente antes de a varredura começar. A captura acontece bem antes de axe.run(), então mudanças no DOM que ocorrem durante a varredura — re-renderizações de SPA, atualizações de useEffect, animações, requisições em andamento — não são refletidas. Em aplicativos de página única, esse desvio é comum.

Custo e suporte ao cliente

Se a imagem é renderizada embutida depende do seu cliente MCP. O servidor sempre retorna um bloco de imagem válido no padrão, mas alguns clientes colapsam os resultados das ferramentas ou omitem as pré-visualizações de imagem — o VS Code com Copilot exibe, enquanto o Cursor e Claude Desktop podem não. Uma pré-visualização ausente é uma limitação de exibição do cliente, não uma falha de captura.

Salvando capturas de tela em disco

A captura de tela também pode ser gravada em um arquivo, o que é uma maneira confiável de ver uma captura em um cliente que não renderiza imagens embutidas. Defina saveTo para um caminho absoluto:

{
  "url": "http://localhost:3000",
  "screenshot": { "saveTo": "/Users/me/Desktop/home.png" }
}

Ou defina save: true para deixar o servidor escolher o nome do arquivo:

{
  "url": "http://localhost:3000",
  "screenshot": { "save": true }
}

O caminho absoluto que foi gravado retorna no array de messages da resposta, então seu agente pode lhe dizer onde encontrar o arquivo.

O salvamento aplica-se a apenas varreduras bem-sucedidas. Se a varredura falhar após a captura da captura de tela, a imagem é retornada embutida junto com o erro, independentemente de inline, e nunca é gravada no disco.

Quando a captura falha

A captura de tela é melhor esforço e nunca falha uma varredura. Se a captura atingir o tempo limite, a varredura ainda retorna seus resultados com uma nota na matriz messages da resposta:

Screenshot capture failed: <reason>

Se a a própria varredura falhar após a captura da captura de tela, a imagem é retornada com a resposta de erro mesmo assim — o estado visual da página no momento em que algo deu errado é geralmente a evidência de depuração mais útil que você tem.

Regras Avançadas

Além do conjunto de regras padrão do axe-core, a ferramenta analyze pode executar Regras Avançadas — testes automatizados que utilizam capturas de tela, visão computacional e modelos de linguagem de grande porte para identificar problemas que axe-core sozinho não pode, como cabeçalhos que apenas parecem cabeçalhos ou imagens informativas com texto alternativo inútil.

Qual predefinição é executada é determinada pela Configuração Axe de sua organização, e — onde seu administrador permitir — pode ser sobrescrita por servidor com AXE_ADVANCED_RULES ou por varredura com o argumento advancedRules:

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough"
}

Cada resposta reporta a predefinição que realmente foi executada e de onde ela veio:

{
  "advancedRules": {
    "value": "thorough",
    "source": "tool_arg"
  }
}

As Regras Avançadas vêm com sua assinatura do Axe DevTools para Web — a mesma que lhe dá o Axe MCP Server. Elas adicionam aproximadamente 15–20 segundos a uma varredura, consomem Créditos de IA, e são o único caso em que analyze envia dados da página (uma captura de tela de página inteira mais a estrutura da página) para a Deque para avaliação. Veja Regras Avançadas para predefinições, precedência, mensagens de degradação e detalhes de privacidade.

Principais Benefícios

• Testes de Navegador Real - Testa a página realmente renderizada, não apenas o código-fonte, garantindo resultados precisos
• Padrões da Organização - Respeita as configurações de configuração do Axe da sua equipe para testes consistentes entre todos os usuários
• Cobertura Abrangente - Aproveita a plataforma Axe líder do setor
• Teste Responsivo - Teste em dimensões específicas de viewport para identificar problemas de acessibilidade específicos de breakpoint
• Varreduras Focalizadas - Delimite uma varredura para uma região específica, iframe ou raiz de sombra com o parâmetro selector
• Páginas Autenticadas e Interativas - Varra páginas após um login, dispense banners de cookies ou espere por conteúdo dinâmico usando ações before
• Cookies de Sessão e Ambiente - Aterrisse já autenticado ou direcione para um ambiente específico, injetando cookies antes da navegação com o parâmetro cookies
• Contexto Visual - Retorne uma captura de tela da página juntamente com o relatório com o parâmetro screenshot, mesmo quando uma varredura falha
• Regras Avançadas - Identifique problemas que requerem raciocínio visual ou contextual, em um limiar de confiança controlado pela sua organização
• Testes Guiados Inteligentes - Execute os IGTs de Teclado, Elementos Interativos e Diálogo Modal contra a mesma página na mesma chamada com o parâmetro igtTools

Saída

A ferramenta retorna uma resposta JSON estruturada contendo:

• Todas as violações de acessibilidade encontradas
• Níveis de severidade das violações (crítico, grave, moderado, leve)
• Seletores de elemento específico e código-fonte
• IDs e descrições de regras
• Um bloco advancedRules relatando a predefinição Regras Avançadas que foi executada e de onde ela veio
• Uma matriz messages carregando quaisquer anotações sobre a execução (por exemplo, uma captura de tela falhada, uma execução degradada de regras avançadas ou o caminho para onde uma captura de tela foi salva)

Quando screenshot está definido, um bloco de conteúdo de imagem segue o relatório. Quando igtTools está definido, os resultados do IGT são retornados juntamente com os resultados do Axe, chaveados pelo nome do IGT.