Erste Schritte mit Maestro

Axe DevTools Mobile für Maestro bringt eingebautes Barrierefreiheits-Scanning zu Maestro, angetrieben von Axe DevTools für Mobile SDKs. Wenn Sie Ihre UI-Testabläufe damit ausführen, können Sie in Ihrem YAML einfach automatisierte Barrierefreiheitsprüfungen mit zwei Befehlen aufrufen: axeStartScanSession und axeScan.

Erfordert

• macOS oder Linux — der Installer erfordert eine Unix-Shell.
  • macOS: unterstützt sowohl Android-Emulator als auch iOS-Simulator
  • Linux: unterstützt nur den Android-Emulator (iOS-Simulatoren sind nur auf macOS verfügbar)
• Java 17+ — verifizieren Sie mit java -version
• curl und unzip — vorinstalliert auf macOS und den meisten Linux-Distributionen
• Android-Emulator oder iOS-Simulator mit Ihrer installierten App
• Axe DevTools Mobile API-Schlüssel
• Axe Developer Hub Projekt-ID

(Hinweis: Windows-Unterstützung kommt bald.)

Installation

1. Wenn Sie zuvor das öffentliche Maestro über Homebrew installiert haben, deinstallieren Sie es zuerst, um PATH-Konflikte zu vermeiden:

   brew uninstall maestro

2. Sie benötigen ein Identitätstoken von Deques privatem Artifactory. Wenn Sie keines haben, folgen Sie den Schritten in Erste Schritte mit Deques privatem Artifactory.

   Stellen Sie sicher, dass DQ_AGORA_IDENTITY_TOKEN in Ihrer Umgebung gesetzt ist, und führen Sie dann den folgenden Befehl auf macOS oder Linux aus:

   curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
   "https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | bash

   Um eine bestimmte Version zu installieren, fügen Sie dies dem Bash-Befehl hinzu:

   curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
   "https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | MAESTRO_VERSION=1.0.0 bash

3. Öffnen Sie ein neues Terminal und überprüfen Sie, dass maestro --version die Axe DevTools-Version anzeigt.

   maestro --version

Schnellstart

1. Erstellen Sie eine Ablaufdatei.

   Erstellen Sie eine Datei namens accessibility-check.yaml und fügen Sie den folgenden Codeausschnitt hinzu:

   appId: com.example.myapp
   ---
   - launchApp
   - axeStartScanSession:
       apiKey: "YOUR_API_KEY"
       projectId: "YOUR_PROJECT_ID"
   - axeScan

   Ersetzen Sie com.example.myapp durch den Paketnamen Ihrer App (Android) oder die Bundle-ID (iOS) und ergänzen Sie Ihren Axe DevTools Mobile API-Schlüssel und die Projekt-ID aus dem Axe Developer Hub.

2. Führen Sie den Ablauf aus.

   Für iOS:

   maestro test --device <DEVICE_ID> accessibility-check.yaml

   Für Android:

   maestro test --device <DEVICE_ID> accessibility-check.yaml

   Bezüglich der Ablaufdatei, die Sie gerade erstellt haben, wird Maestro Ihre App starten, eine Axe DevTools-Scansitzung initialisieren und einen Barrierefreiheits-Scan auf dem aktuellen Bildschirm durchführen. Die Ergebnisse werden automatisch an den Axe Developer Hub hochgeladen.

   note

   Die ‚DEVICE_ID‘ ist ein eindeutiger Bezeichner, den Maestro für die Maschinen verwendet, auf denen Sie Ihre Tests ausführen. Besuchen Sie Maestros Dokumentation, um zu erfahren, wie Sie die Geräte-ID finden.

Umgebungsvariablen für Anmeldedaten verwenden

Das Hartcodieren von API-Schlüsseln in YAML-Dateien wird nicht empfohlen. Verwenden Sie stattdessen Maestro's Variableninterpolation mit Umgebungsvariablen.

Hinweis: Maestro injiziert automatisch nur Shell-Umgebungsvariablen, die mit MAESTRO_ beginnen. Verwenden Sie das Präfix MAESTRO_ für alle Variablen, die Sie in Ihren YAML-Abläufen zur Verfügung haben möchten.

Fügen Sie Folgendes zu Ihrem Shell-Profil hinzu (z. B. ~/.zshrc oder ~/.bashrc):

export MAESTRO_AXE_API_KEY="YOUR_API_KEY"
export MAESTRO_AXE_PROJECT_ID="YOUR_PROJECT_ID"

Beziehen Sie sich dann in Ihrem YAML darauf:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

Alternativ können Sie diese Umgebungsvariablen Inline beim Ausführen übergeben:

Für iOS:

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

Für Android:

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

Befehlsreferenz

axeStartScanSession

Initialisieren Sie eine Axe DevTools-Scansitzung und stellen Sie die notwendigen Anmeldeinformationen für axeStartScanSession bereit. Rufen Sie dies einmal auf, bevor der erste axeScan in Ihrem Ablauf erscheint.

- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://..."

axeScan

Verwenden Sie axeScan, um einen Barrierefreiheitsscan des aktuellen Bildschirms durchzuführen. Wenn axeStartScanSession zuvor im Ablauf aufgerufen wurde, werden die Ergebnisse in den Axe Developer Hub hochgeladen.

# Simple form (all defaults):
- axeScan

Beispiele

Einen einzelnen Bildschirm scannen

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

Mehrere Bildschirme in einem Durchlauf scannen

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Scan the home screen
- axeScan

# Navigate and scan the settings screen
- tapOn: "Settings"
- axeScan

# Navigate and scan the profile screen
- tapOn: "Profile"
- axeScan

Scannen mit einer benutzerdefinierten Axe-Konto-URL

Für On-Premises- oder private Cloud-Deployments von Axe DevTools ist ein axeAccountURL erforderlich:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://axe.YOUR_COMPANY.com"
- axeScan

Nicht-blockierender Barrierefreiheitsscan

Verwenden Sie optional: true mit axeScan, um den Scan durchzuführen, ohne den gesamten Ablauf zu unterbrechen, wenn der Scan auf einen Fehler stößt:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    optional: true
- axeScan:
    optional: true

# The flow continues regardless of scan results
- tapOn: "Continue"

Kombinieren Sie Barrierefreiheitsscans mit UI-Tests

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Test login flow and scan each screen
- assertVisible: "Welcome"
- axeScan:
    label: "Login screen"

- tapOn: "Email"
- inputText: "user@example.com"
- tapOn: "Password"
- inputText: "password123"
- tapOn: "Sign In"

- assertVisible: "Dashboard"
- axeScan:
    label: "Dashboard after login"

Ergebnisse ansehen

Nach Abschluss eines Scans sind die Ergebnisse im Axe Developer Hub verfügbar - ein zentraler Ort, an dem Ihr gesamtes Team die in Ihrer App gefundenen Barrierefreiheitsprobleme einsehen und verwalten kann. Probleme im Developer Hub sind nach Schweregrad und WCAG-Richtlinien kategorisiert, sodass Ihr Team die Behebung priorisieren kann.

Fehlerbehebung

Wenn Sie auf Probleme stoßen, versuchen Sie Folgendes.

• „Befehl nicht gefunden: maestro“

  Öffnen Sie ein neues Terminal nach der Installation oder führen Sie aus:

  export PATH="$HOME/.maestro/bin:$PATH"

• Java-Versionsfehler

  Axe DevTools Mobile Maestro erfordert Java 17 oder höher. Überprüfen Sie Ihre Java-Version:

  java -version

  Wenn Ihre Version unter 17 liegt, installieren Sie ein neueres JDK (z.B. über Adoptium).