Ferramenta de Análise Mobile

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

A ferramenta analyze_mobile examina a tela que está sendo exibida em um dispositivo móvel em busca de problemas de acessibilidade, usando as regras Axe DevTools Mobile. Funciona com um dispositivo Android ou emulador conectado, e com um simulador iOS iniciado ou um iPhone conectado via USB.

note

analyze_mobile requer uma assinatura Axe DevTools Mobile. Não faz parte dos Planos Gratuitos ou Premium, que cobrem a varredura da web.

O que Faz

  1. Autenticação - Valida sua credencial Axe DevTools Mobile: seja uma AXE_MOBILE_API_KEY ou um token de acesso OAuth 2.0 para uma conta com direito ao Axe DevTools Mobile
  2. Configuração do Dispositivo - Usa adb (Android) ou xcodebuild (iOS) em sua máquina para instalar e iniciar o servidor de escaneamento da Deque no dispositivo
  3. Escaneamento de Acessibilidade - Examina a tela que está aberta no dispositivo, usando as regras padrão do Axe DevTools Mobile
  4. Entrega de Resultados - Retorna violações, verificações incompletas e aprovações, cada uma com detalhes suficientes de localização para que seu agente encontre a visualização no seu código-fonte

Requisitos

A ferramenta aparece no seu cliente MCP apenas quando todos os seguintes critérios forem verdadeiros:

  • A distribuição npm. O escaneamento móvel dirige um dispositivo ou simulador conectado à sua máquina, ao qual um contêiner não pode acessar.
  • Uma credencial Axe DevTools Mobile. Configure AXE_MOBILE_API_KEY para uma chave de API Axe DevTools Mobile do Portal de Contas Axe, ou entre com OAuth 2.0 usando uma conta com direito ao Axe DevTools Mobile.
  • Os pacotes do scanner, instalado junto ao servidor. Veja Configuração.

Cada plataforma também precisa de ferramentas na máquina que executa o servidor:

Plataforma Host Necessidades
Android macOS, Windows, Linux Android SDK Platform-Tools, com adb no seu PATH. Um dispositivo com depuração USB ativada, ou um emulador rodando.
Simulador iOS apenas macOS Xcode (não apenas as Ferramentas de Linha de Comando), selecionado com xcode-select. Um simulador iniciado.
iPhone (físico) apenas macOS Xcode, um iPhone conectado por cabo USB com Modo Desenvolvedor ativado, e uma conta de desenvolvedor Apple para assinar o WebDriverAgent. Veja Escaneando um iPhone físico.

Configuração

1. Adicione os pacotes do scanner ao seu comando de servidor

A distribuição npm executa o servidor com npx, portanto adicione os pacotes do scanner ao mesmo comando:

  • @deque/axe-appium3-uiautomator2-server para Android
  • @deque/axe-appium3-webdriveragent-assets para iOS

No macOS, instale ambos, mesmo que você escaneie apenas uma plataforma. No Windows e Linux, instale apenas o pacote Android. O servidor busca ambos na inicialização, e se algum estiver faltando, ele não oferece a ferramenta.

macOS, ambas as plataformas:

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "axe-mcp-server",
        "-p",
        "@deque/axe-appium3-uiautomator2-server@^1.7.0",
        "-p",
        "@deque/axe-appium3-webdriveragent-assets@^1.7.0",
        "axe-mcp-server"
      ],
      "env": {
        "AXE_MOBILE_API_KEY": "${AXE_MOBILE_API_KEY}"
      }
    }
  }
}

Windows e Linux, apenas Android:

"args": [
  "-y",
  "-p",
  "axe-mcp-server",
  "-p",
  "@deque/axe-appium3-uiautomator2-server@^1.7.0",
  "axe-mcp-server"
]

O exemplo utiliza o formato .mcp.json de Claude Code. Coloque o mesmo args na configuração de seu próprio cliente; consulte o guia de configuração para Claude Code, Cursor ou VS Code com Copilot. Se faltar um pacote, o servidor o nomeia em seu log de inicialização.

2. Defina suas credenciais

Defina uma das seguintes opções:

  • Chave de API: Defina AXE_MOBILE_API_KEY para um Chave de API do Axe DevTools Mobile do Portal da Conta Axe.
  • OAuth 2.0: Faça login uma vez com npx @deque/axe-auth login, usando uma conta habilitada para Axe DevTools Mobile. Em seguida, execute o servidor sob @deque/axe-auth run: coloque os mesmos argumentos npx do passo 1 após o --, e não inclua AXE_MOBILE_API_KEY. Veja OAuth 2.0.

Se você também usar as ferramentas web com uma chave de API, configure AXE_API_KEY junto com AXE_MOBILE_API_KEY. Uma chave de API não pode ser combinada com AXE_ACCESS_TOKEN; veja Referência de Configuração.

3. Conecte um dispositivo

Verifique se o dispositivo está visível antes de fazer a varredura:

  • Android: Execute adb devices. Seu dispositivo ou emulador deve estar listado com o estado device. Um estado de unauthorized significa que o dispositivo ainda não aceitou o aviso de depuração USB; offline significa que adb não pode alcançá-lo.
  • iOS: Execute xcrun simctl list devices booted para ver os simuladores inicializados. Um iPhone físico deve aparecer na janela Dispositivos e Simuladores do Xcode.

4. Execute uma primeira varredura

Abra a tela que deseja escanear, então informe seu agente.

Android:

Scan the screen on my Android emulator for accessibility issues

iOS:

Scan the screen on my iPhone simulator for accessibility issues

Para iOS, seu agente envia o ID do bundle do aplicativo com a varredura. Ele pode consultá-lo em seu projeto Xcode, ou você pode nomeá-lo no comando.

tip

A primeira varredura em iOS compila o WebDriverAgent, o que pode levar até 15 minutos. Varreduras posteriores no mesmo dispositivo são muito mais rápidas.

Parâmetros

Parâmetro Obrigatório Descrição
platform Sim "android" ou "ios"
bundleId Sim (apenas iOS) O ID do bundle do aplicativo na tela, como com.example.app
udid Não (apenas iOS) O UDID do simulador ou iPhone a ser escaneado. Quando omitido, o servidor usa o simulador inicializado, ou então o iPhone conectado.

Escolha um dispositivo Android. Não há parâmetro de dispositivo para Android. Quando um dispositivo ou emulador está pronto, o servidor o escaneia. Quando vários estão prontos, defina ANDROID_SERIAL no ambiente do servidor para a lista serial que adb devices fornece para o que você quer.

Encontre o ID do bundle. É o PRODUCT_BUNDLE_IDENTIFIER em seu projeto Xcode, ou o Info.plist do aplicativo. Informe seu agente onde procurar, ou inclua o ID do bundle no seu comando.

Comande seu agente de IA em linguagem natural. O agente traduz sua intenção em uma chamada de ferramenta:

Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.

O agente resolve o comando e chama analyze_mobile com um payload similar a:

{
  "platform": "ios",
  "bundleId": "com.example.myapp"
}

Resultados

A ferramenta retorna um summary da varredura e três listas de achados: violations, incomplete e passes.

Achados

Cada entrada em violations, incomplete e passes tem os seguintes campos:

Campo Descrição
ruleId A regra do Axe DevTools Mobile, como ColorContrast
summary Uma breve descrição da regra
impact Critical, Serious, Moderate, ou Minor
standard O padrão ao qual a regra se corresponde, como WCAG 2.1
successCriteria O critério de sucesso ao qual a regra se corresponde, como 1.4.3
identifier O identificador definido pelo desenvolvedor para a visualização: accessibilityIdentifier no iOS, ou o ID de recurso no Android, mostrado como #name, ou null quando a visualização não o possui
viewPath O caminho da raiz da tela até a visualização, como uma lista de nomes de classes, com o identificador de cada visualização entre parênteses quando possui um, como Button(#login_button)
bounds A posição da exibição na tela, como left, top, right, e bottom
accessibleName O nome que a tecnologia assistiva anuncia para a exibição, ou null
props Evidências específicas da regra, como as cores e a proporção medida em uma verificação de contraste, com campos que variam conforme a regra

identifier e viewPath são como o seu agente encontra a exibição no seu código-fonte. Um identifier é a correspondência mais direta: procure por ele no projeto. Quando uma exibição não tem identificador, viewPath mostra onde ela está, pelo nome da classe e pelos ancestrais mais próximos que tenham um.

Regras

analyze_mobile executa as regras do Axe DevTools Mobile para cada plataforma:

analyze_mobile executa as regras padrão do Axe DevTools Mobile. Ainda não aplica a configuração de regra global móvel da sua organização.

Regras Avançadas e Testes Guiados Inteligentes são apenas para web e não são executados em varreduras móveis.

Escaneando um iPhone Físico

Um iPhone físico precisa de um pouco mais do que um simulador:

  • Conecte-o com um cabo USB. Um telefone emparelhado com seu Mac via Wi-Fi não pode ser escaneado.
  • Ative o Modo Desenvolvedor em Ajustes > Privacidade e Segurança > Modo Desenvolvedor, em seguida reinicie o telefone.
  • Confie no Mac. Desbloqueie o telefone e toque em Confiar quando solicitado.
  • Mantenha-o desbloqueado, com a tela ligada, durante a varredura.
  • Assine o WebDriverAgent com sua conta de desenvolvedor Apple. O servidor não define uma identidade de assinatura para você. Abra WebDriverAgent.xcodeproj no Xcode, escolha sua Equipe em Assinatura e Capacidades, e deixe o Xcode criar um perfil de provisionamento.

Quando a assinatura falha, a varredura retorna uma mensagem dizendo o que está faltando, como uma equipe de desenvolvimento ou um perfil de provisionamento.

Resolução de Problemas

Se analyze_mobile não aparecer no seu cliente, verifique Requisitos e o log de inicialização do servidor, que menciona qualquer pacote de scanner ausente. Reinicie a sessão MCP do seu cliente após alterar a configuração.

Para outros problemas, as mensagens de erro do servidor dizem qual é o problema. As que precisam de mais do que a mensagem:

Mensagem O que fazer
AXE_MOBILE_API_KEY is not supported in the Docker distribution O servidor se recusa a iniciar no Docker com uma chave móvel. Mude para a distribuição npm.
No Android device or emulator found, or the device is not ready Inicie um emulador ou conecte um dispositivo com depuração USB ativada e aceite o prompt no dispositivo. Verifique adb devices: o estado deve ser device, não unauthorized ou offline.
More than one Android device is ready Defina ANDROID_SERIAL para o número de série do dispositivo a ser escaneado, ou desconecte os outros.
The device named by ANDROID_SERIAL is not ready Compare ANDROID_SERIAL com a coluna da esquerda de adb devices.
An iOS scan needs the bundleId of the app on screen Inclua o ID do pacote em seu prompt, ou diga ao seu agente onde encontrá-lo.
xcodebuild not found Instale o Xcode pela App Store. Se ele já estiver instalado, selecione-o: sudo xcode-select -s /Applications/Xcode.app. Somente as Ferramentas de Linha de Comando não são suficientes.
The iPhone is not connected by USB Um telefone emparelhado via Wi-Fi não pode ser escaneado. Conecte-o com um cabo USB.
Code signing failed: … Assine o WebDriverAgent com sua conta de desenvolvedor Apple. Veja Escaneando um iPhone físico.
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked Siga os passos em Escaneando um iPhone físico.
The on-device scan server did not start within …ms Aumente MOBILE_SERVER_READY_TIMEOUT_MS e tente novamente.
This account does not have an active axe DevTools Mobile subscription Peça ao administrador da sua conta para adicionar uma assinatura do Axe DevTools Mobile, depois inicie uma nova sessão.
This API key belongs to a different product Certifique-se de que AXE_MOBILE_API_KEY contenha uma chave do Axe DevTools Mobile e AXE_API_KEY contenha uma chave web, depois inicie uma nova sessão.
`analyze` needs a web credential (ou remediate, igt) Somente AXE_MOBILE_API_KEY está configurado, o que não autoriza as ferramentas web. Adicione AXE_API_KEY, ou mude para OAuth e remova AXE_MOBILE_API_KEY, depois inicie uma nova sessão.

Para qualquer outra falha, configure LOG_LEVEL=debug no ambiente do servidor. Para uma falha de construção do iOS, o log de depuração inclui a saída do próprio Xcode. Veja também a página geral de Resolução de Problemas.

Limitações

  • Uma tela por chamada. A ferramenta analisa o que está na tela e não navega no aplicativo. Abra cada tela você mesmo, depois faça a análise.
  • Uma análise de cada vez, por máquina. O servidor realiza uma análise móvel de cada vez, e as análises Android usam uma porta local fixa, portanto, execute apenas um servidor de análise móvel por máquina.
  • Sem Regras Avançadas ou Testes Guiados Inteligentes. Ambos são exclusivos para a web.
  • Sem captura de tela. Ao contrário de analyze, a ferramenta não retorna uma imagem da tela.
  • Sem atualizações de progresso durante a primeira compilação iOS. A chamada permanece silenciosa até que o WebDriverAgent seja compilado e a análise termine.
  • Sem remediação móvel. A ferramenta remediate aceita apenas problemas na web.