Analizza Strumento 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

Lo strumento analyze_mobile esegue la scansione dello schermo attualmente visualizzato su un dispositivo mobile per problemi di accessibilità, utilizzando le regole Axe DevTools Mobile. Funziona con un dispositivo Android collegato o emulatori, e con un simulatore iOS avviato o un iPhone collegato via USB.

note

analyze_mobile richiede un abbonamento Axe DevTools Mobile. Non fa parte dei Piani Gratuiti o Premium, che coprono la scansione web.

Cosa Fa

  1. Autenticazione - Convalida la tua credenziale Axe DevTools Mobile: o una AXE_MOBILE_API_KEY o un token di accesso OAuth 2.0 per un account che ha diritto a Axe DevTools Mobile
  2. Configurazione Dispositivo - Utilizza adb (Android) o xcodebuild (iOS) sul tuo computer per installare e avviare il server di scansione di Deque sul dispositivo
  3. Scansione Accessibilità - Scansiona lo schermo aperto sul dispositivo, usando le regole predefinite di Axe DevTools Mobile
  4. Consegna Risultati - Restituisce violazioni, verifiche incomplete e passaggi, ciascuno con dettagli sulla posizione sufficienti affinché il tuo agente trovi la vista nel codice sorgente

Requisiti

Lo strumento appare nel tuo client MCP solo quando sono vere tutte le seguenti condizioni:

  • La distribuzione npm. La scansione mobile comanda un dispositivo o simulatore collegato al tuo computer, che un contenitore non può raggiungere.
  • Una credenziale Axe DevTools Mobile. Imposta AXE_MOBILE_API_KEY su una chiave API Axe DevTools Mobile del portale dell'account Axe, o accedi con OAuth 2.0 usando un account con diritto a Axe DevTools Mobile.
  • I pacchetti di scanner, installato insieme al server. Vedi Configurazione.

Ogni piattaforma necessita anche di strumenti sul computer che esegue il server:

Piattaforma Host Necessita
Android macOS, Windows, Linux Strumenti Piattaforma SDK Android, con adb sul tuo PATH. Un dispositivo con debug USB attivato, o un emulatore in esecuzione.
Simulatore iOS solo macOS Xcode (non solo gli strumenti da riga di comando), selezionato con xcode-select. Un simulatore avviato.
iPhone (fisico) solo macOS Xcode, un iPhone collegato tramite cavo USB con Modalità Sviluppatore attivata, e un account sviluppatore Apple per firmare WebDriverAgent. Vedi Scansione di un iPhone fisico.

Configurazione

1. Aggiungi i pacchetti di scanner al comando del tuo server

La distribuzione npm esegue il server con npx, quindi aggiungi i pacchetti di scanner allo stesso comando:

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

Su macOS, installa entrambi, anche se scannerizzi solo una piattaforma. Su Windows e Linux, installa solo il pacchetto Android. Il server cerca entrambi all'avvio e se ne manca uno non offre lo strumento.

macOS, entrambe le piattaforme:

{
  "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, solo Android:

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

L'esempio utilizza il formato .mcp.json di Claude Code. Inserisci lo stesso args nella configurazione del tuo client; consulta la guida all'installazione per Claude Codice, Cursore o VS Code con Copilot. Se manca un pacchetto, il server lo nomina nel suo registro di avvio.

2. Imposta le tue credenziali

Imposta una di quanto segue:

  • Chiave API: Imposta AXE_MOBILE_API_KEY a un Chiave API di Axe DevTools Mobile dal Portale Account Axe.
  • OAuth 2.0: Accedi una volta con npx @deque/axe-auth login, usando un account abilitato a Axe DevTools Mobile. Poi esegui il server sotto @deque/axe-auth run: inserisci gli stessi argomenti npx dal passaggio 1 dopo il -- e ometti AXE_MOBILE_API_KEY. Consulta OAuth 2.0.

Se usi anche gli strumenti web con una chiave API, imposta AXE_API_KEY insieme a AXE_MOBILE_API_KEY. Una chiave API non può essere combinata con AXE_ACCESS_TOKEN; consulta Riferimento Configurazione.

3. Collega un dispositivo

Controlla che il dispositivo sia visibile prima di eseguire la scansione:

  • Android: Esegui adb devices. Il tuo dispositivo o emulatore dovrebbe essere elencato con lo stato device. Uno stato di unauthorized significa che il dispositivo non ha ancora accettato il prompt di debug USB; offline significa che adb non riesce a raggiungerlo.
  • iOS: Esegui xcrun simctl list devices booted per vedere i simulatori avviati. Un iPhone fisico dovrebbe apparire nella finestra Dispositivi e Simulatori di Xcode.

4. Esegui una prima scansione

Apri la schermata che vuoi scansionare, poi informa il tuo agente.

Android:

Scan the screen on my Android emulator for accessibility issues

iOS:

Scan the screen on my iPhone simulator for accessibility issues

Per iOS, il tuo agente invia l'ID del bundle dell'app con la scansione. Può cercarlo nel tuo progetto Xcode, oppure puoi nominarlo nel prompt.

tip

La prima scansione iOS costruisce WebDriverAgent, che può richiedere fino a 15 minuti. Le scansioni successive sullo stesso dispositivo sono molto più rapide.

Parametri

Parametro Richiesto Descrizione
platform Sì "android" o "ios"
bundleId Sì (solo iOS) L'ID del bundle dell'app a schermo, come com.example.app
udid No (solo iOS) Il UDID del simulatore o iPhone da scansionare. Quando omesso, il server usa il simulatore avviato, oppure l'iPhone collegato.

Scegli un dispositivo Android. Non c'è un parametro dispositivo per Android. Quando un dispositivo o emulatore è pronto, il server lo scansiona. Quando ce ne sono diversi pronti, imposta ANDROID_SERIAL nell'ambiente del server alla lista seriale adb devices per quello che desideri.

Trova l'ID del bundle. È il PRODUCT_BUNDLE_IDENTIFIER nel tuo progetto Xcode, oppure il Info.plist dell'app. Dì al tuo agente dove cercare oppure includi l'ID del bundle nel tuo prompt.

Chiedi al tuo agente AI in linguaggio naturale. L'agente traduce la tua intenzione nella chiamata allo strumento:

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

L'agente risolve il prompt e chiama analyze_mobile con un payload simile a:

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

Risultati

Lo strumento restituisce un summary della scansione e tre elenchi di risultati: violations, incomplete e passes.

Risultati

Ogni voce in violations, incomplete e passes ha questi campi:

Campo Descrizione
ruleId La regola di Axe DevTools Mobile, come ColorContrast
summary Una breve descrizione della regola
impact Critical, Serious, Moderate o Minor
standard Lo standard a cui la regola fa riferimento, come WCAG 2.1
successCriteria Il criterio di successo a cui la regola fa riferimento, come 1.4.3
identifier L'identificatore impostato dallo sviluppatore della vista: accessibilityIdentifier su iOS, o l'ID della risorsa su Android, mostrato come #name, o null quando la vista non ne ha uno
viewPath Il percorso dalla radice della schermata alla vista, come un elenco di nomi di classi, con l'identificatore di ciascuna vista tra parentesi quando ce l'ha, come Button(#login_button)
bounds La posizione della vista sullo schermo, come left, top, right e bottom
accessibleName Il nome che la tecnologia assistiva annuncia per la vista, o null
props Evidenze specifiche della regola, come i colori e il rapporto misurato da un controllo del contrasto, con campi che variano in base alla regola

identifier e viewPath sono come il tuo agente trova la vista nel tuo codice sorgente. Un identifier è la corrispondenza più diretta: cercalo nel progetto. Quando una vista non ha un identificatore, viewPath mostra dove si trova, per nome di classe e per gli antenati più vicini che ne hanno uno.

Regole

analyze_mobile esegue le regole di Axe DevTools Mobile per ciascuna piattaforma:

analyze_mobile esegue le regole predefinite di Axe DevTools Mobile. Non applica ancora la configurazione globale delle regole mobile della tua organizzazione.

Le Regole Avanzate e i Test Intelligenti Guidati sono solo web e non vengono eseguiti nelle scansioni mobili.

Scansione di un iPhone fisico

Un iPhone fisico ha bisogno di un po' più di un simulatore:

  • Collegalo con un cavo USB. Un telefono abbinato al tuo Mac tramite Wi-Fi non può essere scansionato.
  • Attiva la modalità Sviluppatore sotto Impostazioni > Privacy e Sicurezza > Modalità Sviluppatore, quindi riavvia il telefono.
  • Fidati del Mac. Sblocca il telefono e tocca Fidati quando richiesto.
  • Tienilo sbloccato, con lo schermo acceso, durante la scansione.
  • Firma WebDriverAgent con il tuo account sviluppatore Apple. Il server non imposta un'identità di firma per te. Apri WebDriverAgent.xcodeproj in Xcode, scegli il tuo Team sotto Firma & Capacità, e lascia che Xcode crei un profilo di provisioning.

Quando la firma fallisce, la scansione restituisce un messaggio che indica cosa manca, come un team di sviluppo o un profilo di provisioning.

Risoluzione dei problemi

Se analyze_mobile non appare nel tuo client, controlla Requisiti e il registro di avvio del server, che nomina qualsiasi pacchetto di scanner mancante. Riavvia la sessione MCP del tuo client dopo aver modificato la configurazione.

Per altri problemi, i messaggi di errore del server indicano cosa c'è di sbagliato. Quelli che richiedono più del messaggio:

Messaggio Cosa fare
AXE_MOBILE_API_KEY is not supported in the Docker distribution Il server rifiuta di avviarsi in Docker con una chiave mobile. Passa alla distribuzione npm.
No Android device or emulator found, or the device is not ready Avvia un emulatore o collega un dispositivo con debug USB attivo e accetta il prompt sul dispositivo. Controlla adb devices: lo stato dovrebbe essere device, non unauthorized o offline.
More than one Android device is ready Imposta ANDROID_SERIAL sul seriale del dispositivo da scansionare o disconnetti gli altri.
The device named by ANDROID_SERIAL is not ready Confronta ANDROID_SERIAL con la colonna di sinistra di adb devices.
An iOS scan needs the bundleId of the app on screen Includi l'ID del bundle nel tuo prompt o indica al tuo agente dove trovarlo.
xcodebuild not found Installa Xcode dall'App Store. Se è già installato, selezionalo: sudo xcode-select -s /Applications/Xcode.app. Gli Strumenti da Linea di Comando da soli non sono sufficienti.
The iPhone is not connected by USB Un telefono abbinato tramite Wi-Fi non può essere scansionato. Collegalo con un cavo USB.
Code signing failed: … Firma WebDriverAgent con il tuo account sviluppatore Apple. Vedi Scansione di un iPhone fisico.
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked Segui i passi in Scansione di un iPhone fisico.
The on-device scan server did not start within …ms Alza MOBILE_SERVER_READY_TIMEOUT_MS e prova di nuovo.
This account does not have an active axe DevTools Mobile subscription Chiedi all'amministratore del tuo account di aggiungere un abbonamento a Axe DevTools Mobile, poi inizia una nuova sessione.
This API key belongs to a different product Assicurati che AXE_MOBILE_API_KEY contenga una chiave Axe DevTools Mobile e AXE_API_KEY contenga una chiave web, quindi avvia una nuova sessione.
`analyze` needs a web credential (o remediate, igt) Solo AXE_MOBILE_API_KEY è impostato, il che non autorizza gli strumenti web. Aggiungi AXE_API_KEY, o passa a OAuth e rimuovi AXE_MOBILE_API_KEY, quindi inizia una nuova sessione.

Per qualsiasi altro errore, imposta LOG_LEVEL=debug nell'ambiente del server. Per un errore di build iOS, il registro di debug include l'output di Xcode stesso. Vedi anche la pagina generale Risoluzione dei problemi.

Limitazioni

  • Uno schermo per chiamata. Lo strumento esamina ciò che è sullo schermo e non naviga nell'app. Apri ogni schermo da solo, poi esegui la scansione.
  • Una scansione alla volta, per macchina. Il server esegue una scansione mobile alla volta, e le scansioni Android usano una porta locale fissa, quindi esegui solo un server di scansione mobile per macchina.
  • Nessuna Regola Avanzata o Test Guidato Intelligente. Entrambi sono solo per il web.
  • Nessuno screenshot. A differenza di analyze, lo strumento non restituisce un'immagine dello schermo.
  • Nessun aggiornamento sul progresso durante la prima build iOS. La chiamata rimane silenziosa fino a quando WebDriverAgent non è costruito e la scansione completata.
  • Nessuna correzione mobile. Lo strumento remediate accetta solo problematiche web.