Aan de slag met Maestro

Axe DevTools Mobile voor Maestro brengt ingebouwde toegankelijkheidsscanning naar Maestro, aangedreven door Axe DevTools voor Mobile SDK's. Wanneer je je UI-testflows hiermee uitvoert, kun je eenvoudig geautomatiseerde toegankelijkheidscontroles rechtstreeks in je YAML starten met twee opdrachten: axeStartScanSession en axeScan.

Vereisten

• macOS of Linux — de installer vereist een Unix-shell.
  • macOS: ondersteunt zowel Android-emulator als iOS-simulator
  • Linux: ondersteunt alleen Android-emulator (iOS-simulators zijn exclusief voor macOS)
• Java 17+ — verifieer met java -version
• curl en unzip — vooraf geïnstalleerd op macOS en de meeste Linux-distributies
• Android-emulator of iOS-simulator met je app geïnstalleerd
• Axe DevTools Mobile API-sleutel
• Axe Developer Hub Project-ID

(Opmerking: Ondersteuning voor Windows komt binnenkort.)

Installatie

1. Als je eerder publieke Maestro via Homebrew hebt geïnstalleerd, deïnstalleer deze dan eerst om PATH-conflicten te vermijden:

   brew uninstall maestro

2. Je hebt een identiteitstoken nodig van Deque's private Artifactory. Als je er geen hebt, volg de stappen in Aan de slag met Deque's Private Artifactory.

   Zorg ervoor dat DQ_AGORA_IDENTITY_TOKEN in je omgeving is ingesteld, voer dan het volgende commando uit op macOS of Linux:

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

   Om een specifieke versie te installeren, voeg dit toe aan de bash-opdracht:

   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. Open een nieuwe terminal en controleer of maestro --version de Axe DevTools-versie toont.

   maestro --version

Snel starten

1. Maak een flow-bestand.

   Maak een bestand genaamd accessibility-check.yaml en voeg de volgende codefragment toe:

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

   Vervang com.example.myapp door de pakketnaam van je app (Android) of bundle ID (iOS), en vul je Axe DevTools Mobile API-sleutel en Project-ID van Axe Developer Hub in.

2. Voer de flow uit.

   Voor iOS:

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

   Voor Android:

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

   Met verwijzing naar het flow-bestand dat je zojuist hebt gemaakt, zal Maestro je app starten, een Axe DevTools-sessie voor scannen initialiseren en een toegankelijkheidsscan uitvoeren op het huidige scherm. Resultaten worden automatisch geüpload naar Axe Developer Hub.

   note

   De 'DEVICE_ID' is een unieke identificatie die Maestro gebruikt voor de machines waarop je je tests uitvoert. Bezoek Maestro's documentatie om te leren hoe je het apparaat-ID kunt vinden.

Gebruik omgevingsvariabelen voor referenties

Hardcoderen van API-sleutels in YAML-bestanden wordt niet aanbevolen. Gebruik in plaats daarvan Maestro's variabele interpolatie met omgevingsvariabelen.

Opmerking: Maestro injecteert alleen automatisch shell-omgevingsvariabelen die beginnen met MAESTRO_. Gebruik de MAESTRO_-prefix voor alle variabelen die je beschikbaar wilt maken in je YAML-flows.

Voeg het volgende toe aan je shell-profiel (bijv., ~/.zshrc of ~/.bashrc):

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

Verwijs vervolgens hiernaar in je YAML:

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

Geef deze omgevingsvariabelen eventueel ook inline door tijdens het uitvoeren:

Voor iOS:

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

Voor Android:

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

Opdracht Referentie

axeStartScanSession

Initialiseer een Axe DevTools-sessie voor scannen en verstrek de nodige referenties aan axeStartScanSession. Roep dit één keer aan, vóór de eerste axeScan in je flow.

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

axeScan

Gebruik axeScan om een toegankelijkheidsscan uit te voeren op het huidige scherm. Als axeStartScanSession eerder in de workflow is aangeroepen, worden de resultaten geüpload naar Axe Developer Hub.

# Simple form (all defaults):
- axeScan

Voorbeelden

Een enkel scherm scannen

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

Meerdere schermen in één workflow 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 met een aangepaste Axe Account URL

Voor lokale of privé cloud Axe DevTools implementaties is een axeAccountURL vereist:

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

Niet-blokkerende toegankelijkheidsscan

Gebruik optional: true met axeScan om de scan uit te voeren zonder de hele workflow te laten falen als de scan een fout tegenkomt:

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"

Toegankelijkheidsscans combineren met 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"

Resultaten bekijken

Nadat een scan is voltooid, zijn de resultaten beschikbaar in Axe Developer Hub - een centrale locatie waar je hele team de toegankelijkheidsproblemen in je app kan bekijken en beheren. Problemen in Developer Hub zijn gecategoriseerd op ernst en WCAG-richtlijnen, zodat je team problemen kan prioriteren voor oplossing.

Probleemoplossing

Probeer het volgende als je problemen tegenkomt.

• „Opdracht niet gevonden: maestro“

  Open een nieuwe terminal na de installatie, of voer uit:

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

• Java versie fouten

  Axe DevTools Mobile Maestro vereist Java 17 of hoger. Controleer je Java-versie:

  java -version

  Als je versie lager is dan 17, installeer dan een nieuwere JDK (bijv. via Adoptium).