Analyse Mobile Tool

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

Das analyze_mobile-Werkzeug scannt den aktuell auf einem mobilen Gerät angezeigten Bildschirm auf Barrierefreiheitsprobleme unter Verwendung der Axe DevTools Mobile-Regeln. Es funktioniert mit einem verbundenen Android-Gerät oder Emulator sowie mit einem gestarteten iOS-Simulator oder einem per USB verbundenen iPhone.

note

analyze_mobile benötigt ein Axe DevTools Mobile-Abonnement. Es ist nicht Teil der Kostenlose oder Premium-Pläne, die Web-Scans abdecken.

Funktionalität

  1. Authentifizierung - Validiert Ihr Axe DevTools Mobile-Zertifikat: entweder ein AXE_MOBILE_API_KEY oder ein OAuth 2.0-Zugriffstoken für ein Konto mit Berechtigung zu Axe DevTools Mobile
  2. Geräteeinrichtung - Verwendet adb (Android) oder xcodebuild (iOS) auf Ihrem Computer, um Deques Scan-Server auf dem Gerät zu installieren und zu starten
  3. Barrierefreiheitsscan - Scannt den auf dem Gerät geöffneten Bildschirm unter Verwendung der Standardregeln von Axe DevTools Mobile
  4. Ergebnislieferung - Liefert Verstöße, unvollständige Prüfungen und Erfolge zurück, jeweils mit ausreichend Standortdetails, damit Ihr Agent die Ansicht im Quellcode finden kann

Anforderungen

Das Werkzeug erscheint in Ihrem MCP-Client nur, wenn alle folgenden Bedingungen erfüllt sind:

  • Die npm-Distribution. Mobile Scanning steuert ein mit Ihrem Computer verbundenes Gerät oder einen Simulator, den ein Container nicht erreichen kann.
  • Ein Axe DevTools Mobile-Zertifikat. Setzen Sie AXE_MOBILE_API_KEY auf einen Axe DevTools Mobile-API-Schlüssel aus dem Axe Account Portal oder melden Sie sich mit OAuth 2.0 bei einem Konto an, das zur Nutzung von Axe DevTools Mobile berechtigt ist.
  • Die Scanner-Pakete, neben dem Server installiert. Siehe Einrichtung.

Jede Plattform benötigt zudem Werkzeuge auf dem Computer, der den Server ausführt:

Plattform Host Benötigt
Android macOS, Windows, Linux Android SDK Platform-Tools, mit adb auf Ihrem PATH. Ein Gerät mit aktiviertem USB-Debugging oder ein laufender Emulator.
iOS-Simulator Nur macOS Xcode (nicht nur die Command Line Tools), ausgewählt mit xcode-select. Ein gestarteter Simulator.
iPhone (physisch) Nur macOS Xcode, ein per USB-Kabel verbundenes iPhone mit aktiviertem Entwicklermodus und ein Apple-Entwicklerkonto zum Signieren von WebDriverAgent. Siehe Scannen eines physischen iPhones.

Einrichtung

1. Fügen Sie die Scanner-Pakete zu Ihrem Server-Befehl hinzu

Die npm-Distribution führt den Server mit npx aus, daher fügen Sie die Scanner-Pakete zum gleichen Befehl hinzu:

  • @deque/axe-appium3-uiautomator2-server für Android
  • @deque/axe-appium3-webdriveragent-assets für iOS

Auf macOS, installieren Sie beide, auch wenn Sie nur eine Plattform scannen. Auf Windows und Linux, installieren Sie nur das Android-Paket. Der Server sucht beim Start nach beiden und bietet das Tool nicht an, wenn eines fehlt.

macOS, beide Plattformen:

{
  "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 und Linux, nur Android:

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

Das Beispiel verwendet das Format von Claude Code's .mcp.json. Übernehmen Sie das gleiche args in Ihrer eigenen Client-Konfiguration; siehe den Setup-Guide für Claude Code, Cursor oder VS Code mit Copilot. Wenn ein Paket fehlt, benennt der Server es in seinem Startprotokoll.

2. Legen Sie Ihre Anmeldedaten fest

Legen Sie eine der folgenden Optionen fest:

  • API-Schlüssel: Legen Sie AXE_MOBILE_API_KEY auf einen Axe DevTools Mobile API-Schlüssel aus dem Axe Account Portal fest.
  • OAuth 2.0: Melden Sie sich einmal mit npx @deque/axe-auth login an, indem Sie ein Konto verwenden, das für Axe DevTools Mobile berechtigt ist. Führen Sie dann den Server unter @deque/axe-auth run aus: Übernehmen Sie die gleichen npx Argumente aus Schritt 1 nach dem --, und lassen Sie AXE_MOBILE_API_KEY aus. Siehe OAuth 2.0.

Wenn Sie auch die Web-Tools mit einem API-Schlüssel verwenden, setzen Sie AXE_API_KEY neben AXE_MOBILE_API_KEY. Ein API-Schlüssel kann nicht mit AXE_ACCESS_TOKEN kombiniert werden; siehe Konfigurationsreferenz.

3. Verbinden Sie ein Gerät

Überprüfen Sie, dass das Gerät vor dem Scannen sichtbar ist:

  • Android: Führen Sie adb devices aus. Ihr Gerät oder Emulator sollte mit dem Status device aufgelistet sein. Ein Status von unauthorized bedeutet, dass das Gerät die USB-Debugging-Aufforderung noch nicht akzeptiert hat; offline bedeutet, dass adb es nicht erreichen kann.
  • iOS: Führen Sie xcrun simctl list devices booted aus, um gestartete Simulatoren zu sehen. Ein physisches iPhone sollte im Geräte und Simulatoren-Fenster von Xcode erscheinen.

4. Führen Sie einen ersten Scan durch

Öffnen Sie den Bildschirm, den Sie scannen möchten, und weisen Sie dann Ihren Agenten an.

Android:

Scan the screen on my Android emulator for accessibility issues

iOS:

Scan the screen on my iPhone simulator for accessibility issues

Für iOS sendet Ihr Agent die Bundle-ID der App mit dem Scan. Er kann sie in Ihrem Xcode-Projekt nachschlagen, oder Sie können sie in der Aufforderung benennen.

tip

Der erste iOS-Scan erstellt den WebDriverAgent, was bis zu 15 Minuten dauern kann. Spätere Scans auf demselben Gerät sind viel schneller.

Parameter

Parameter Erforderlich Beschreibung
platform Ja "android" oder "ios"
bundleId Ja (nur iOS) Die Bundle-ID der App auf dem Bildschirm, wie zum Beispiel com.example.app
udid Nein (nur iOS) Die UDID des Simulators oder iPhones, das gescannt werden soll. Wenn weggelassen, verwendet der Server den gestarteten Simulator oder das angeschlossene iPhone.

Wählen Sie ein Android-Gerät. Es gibt keinen Geräte-Parameter für Android. Wenn ein Gerät oder Emulator bereit ist, scannt der Server es. Wenn mehrere bereit sind, setzen Sie ANDROID_SERIAL in der Umgebung des Servers auf die Seriennummer von adb devices für das gewünschte Gerät.

Finden Sie die Bundle-ID. Es ist die PRODUCT_BUNDLE_IDENTIFIER in Ihrem Xcode-Projekt oder die Info.plist der App. Sagen Sie Ihrem Agenten, wo er suchen soll, oder fügen Sie die Bundle-ID Ihrer Eingabe hinzu.

Fordern Sie Ihren KI-Agenten in natürlicher Sprache auf. Der Agent übersetzt Ihre Absicht in den Werkzeugaufruf:

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

Der Agent löst die Eingabe aus und ruft analyze_mobile mit einer Nutzlast ähnlich wie folgt auf:

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

Ergebnisse

Das Tool liefert ein summary des Scans und drei Listen von Ergebnissen: violations, incomplete und passes.

Befunde

Jeder Eintrag in violations, incomplete und passes enthält diese Felder:

Feld Beschreibung
ruleId Die Axe DevTools Mobile Regel, wie zum Beispiel ColorContrast
summary Eine kurze Beschreibung der Regel
impact Critical, Serious, Moderate oder Minor
standard Der Standard, auf den die Regel verweist, wie zum Beispiel WCAG 2.1
successCriteria Das Erfolgskriterium, auf das die Regel verweist, wie zum Beispiel 1.4.3
identifier Die vom Entwickler festgelegte Kennung der Ansicht: accessibilityIdentifier auf iOS oder die Ressourcen-ID auf Android, dargestellt als #name oder null, wenn die Ansicht keine hat
viewPath Der Pfad vom Ursprung des Bildschirms zur Ansicht, als Liste von Klassennamen, wobei für jede Ansicht deren Kennung in Klammern, sofern vorhanden, wie zum Beispiel Button(#login_button)
bounds Die Position der Ansicht auf dem Bildschirm, als left, top, right und bottom
accessibleName Der Name, den die unterstützende Technologie für die Ansicht ankündigt, oder null
props Regel-spezifische Nachweise, wie zum Beispiel die Farben und das Verhältnis, die ein Kontrastcheck gemessen hat, mit Feldern, die je nach Regel variieren

identifier und viewPath sind, wie Ihr Agent die Ansicht in Ihrem Quellcode findet. Ein identifier ist die direkteste Übereinstimmung: durchsuchen Sie das Projekt danach. Wenn eine Ansicht keine Kennung hat, zeigt viewPath, wo sie sich befindet, durch ihren Klassennamen und durch die nächsten Vorfahren, die eine Kennung haben.

Regeln

analyze_mobile führt die Axe DevTools Mobile-Regeln für jede Plattform aus:

analyze_mobile führt die Standard Axe DevTools Mobile-Regeln aus. Sie gelten noch nicht für die mobile globale Regelkonfiguration Ihres Unternehmens.

Erweiterte Regeln und intelligente geführte Tests sind nur für das Web und werden nicht in mobilen Scans ausgeführt.

Scannen eines physischen iPhones

Ein physisches iPhone benötigt etwas mehr als ein Simulator:

  • Verbinden Sie es mit einem USB-Kabel. Ein über WLAN mit Ihrem Mac verbundenes Telefon kann nicht gescannt werden.
  • Schalten Sie den Entwicklermodus ein unter Einstellungen > Datenschutz & Sicherheit > Entwicklermodus, dann starten Sie das Telefon neu.
  • Vertrauen Sie dem Mac. Entsperren Sie das Telefon und tippen Sie auf Vertrauen, wenn es fragt.
  • Halten Sie es entsperrt, mit eingeschaltetem Bildschirm, während des Scannens.
  • Signieren Sie WebDriverAgent mit Ihrem Apple-Entwicklerkonto. Der Server legt keine Signaturidentität für Sie fest. Öffnen Sie WebDriverAgent.xcodeproj in Xcode, wählen Sie Ihr Team unter Signierung & Fähigkeiten und lassen Sie Xcode ein Bereitstellungsprofil erstellen.

Wenn die Signatur fehlschlägt, gibt der Scan eine Nachricht zurück, die besagt, was fehlt, wie zum Beispiel ein Entwicklungsteam oder ein Bereitstellungsprofil.

Fehlerbehebung

Wenn analyze_mobile nicht in Ihrem Client erscheint, überprüfen Sie Anforderungen und das Startprotokoll des Servers, das fehlende Scannerpakete benennt. Starten Sie die MCP-Sitzung Ihres Clients neu, nachdem Sie die Konfiguration geändert haben.

Bei anderen Problemen zeigen die Fehlermeldungen des Servers an, was falsch ist. Diejenigen, die mehr als die Nachricht benötigen:

Nachricht Was tun
AXE_MOBILE_API_KEY is not supported in the Docker distribution Der Server verweigert den Start in Docker mit einem mobilen Schlüssel. Wechseln Sie zur npm-Distribution.
No Android device or emulator found, or the device is not ready Starten Sie einen Emulator oder verbinden Sie ein Gerät mit aktiviertem USB-Debugging und akzeptieren Sie die Aufforderung auf dem Gerät. Überprüfen Sie adb devices: Der Zustand sollte device sein, nicht unauthorized oder offline.
More than one Android device is ready Setzen Sie ANDROID_SERIAL auf die Seriennummer des zu scannenden Geräts oder trennen Sie die anderen.
The device named by ANDROID_SERIAL is not ready Vergleichen Sie ANDROID_SERIAL mit der linken Spalte von adb devices.
An iOS scan needs the bundleId of the app on screen Geben Sie die Bundle-ID in Ihrer Aufforderung an oder informieren Sie Ihren Agenten, wo er sie finden kann.
xcodebuild not found Installieren Sie Xcode aus dem App Store. Wenn es installiert ist, wählen Sie es aus: sudo xcode-select -s /Applications/Xcode.app. Die Befehlszeilentools allein reichen nicht aus.
The iPhone is not connected by USB Ein über WLAN verbundenes Telefon kann nicht gescannt werden. Verbinden Sie es mit einem USB-Kabel.
Code signing failed: … Signieren Sie WebDriverAgent mit Ihrem Apple-Entwicklerkonto. Siehe Scannen eines physischen iPhones.
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked Befolgen Sie die Schritte in Scannen eines physischen iPhones.
The on-device scan server did not start within …ms Erhöhen Sie MOBILE_SERVER_READY_TIMEOUT_MS und versuchen Sie es erneut.
This account does not have an active axe DevTools Mobile subscription Bitten Sie Ihren Kontoadministrator, ein Axe DevTools Mobile-Abonnement hinzuzufügen, und starten Sie dann eine neue Sitzung.
This API key belongs to a different product Stellen Sie sicher, dass AXE_MOBILE_API_KEY einen Axe DevTools Mobile-Schlüssel und AXE_API_KEY einen Web-Schlüssel enthält, und starten Sie dann eine neue Sitzung.
`analyze` needs a web credential (oder remediate, igt) Nur AXE_MOBILE_API_KEY ist gesetzt, was die Web-Tools nicht autorisiert. Fügen Sie AXE_API_KEY hinzu oder wechseln Sie zu OAuth und entfernen Sie AXE_MOBILE_API_KEY, dann starten Sie eine neue Sitzung.

Bei jedem anderen Fehler setzen Sie LOG_LEVEL=debug in der Serverumgebung. Bei einem iOS-Build-Fehler enthält das Debug-Log Xcodes eigene Ausgabe. Siehe auch die allgemeine Seite Fehlerbehebung.

Einschränkungen

  • Ein Bildschirm pro Anruf. Das Tool scannt, was auf dem Bildschirm ist, und navigiert nicht in der App. Öffne jeden Bildschirm selbst und scanne ihn dann.
  • Ein Scan nach dem anderen, pro Gerät. Der Server führt jeweils einen mobilen Scan durch, und Android-Scans verwenden einen festgelegten lokalen Port. Daher sollte nur ein mobiler Scan-Server pro Gerät betrieben werden.
  • Keine erweiterten Regeln oder Intelligent Guided Tests. Beide sind nur im Web verfügbar.
  • Kein Screenshot. Anders als analyze liefert das Tool kein Bild des Bildschirms zurück.
  • Keine Fortschrittsaktualisierungen während des ersten iOS-Builds. Der Anruf bleibt stumm, bis WebDriverAgent erstellt und der Scan abgeschlossen ist.
  • Keine mobile Behebung. Das remediate Tool akzeptiert nur Web-Probleme.