Primeros pasos con Maestro

Axe DevTools Mobile para Maestro lleva el escaneo de accesibilidad incorporado a Maestro, impulsado por las SDKs de Axe DevTools para móviles. Cuando ejecuta sus flujos de prueba de IU con él, puede invocar fácilmente verificaciones de accesibilidad automatizadas directamente en su YAML con dos comandos: axeStartScanSession y axeScan.

Requisitos

• macOS o Linux — el instalador requiere un shell de Unix.
  • macOS: admite tanto el emulador de Android como el simulador de iOS
  • Linux: solo admite el emulador de Android (los simuladores de iOS son exclusivos de macOS)
• Java 17+ — verifique con java -version
• curl y unzip — preinstalados en macOS y en la mayoría de las distribuciones de Linux
• Emulador de Android o simulador de iOS con su aplicación instalada
• Clave de API de Axe DevTools Mobile
• ID de proyecto del Axe Developer Hub

(Nota: El soporte para Windows llegará pronto.)

Instalación

1. Si instaló previamente Maestro público a través de Homebrew, desinstálelo primero para evitar conflictos de PATH:

   brew uninstall maestro

2. Necesitará un token de identidad del Artifactory privado de Deque. Si no tiene uno, siga los pasos en Primeros pasos con el Artifactory privado de Deque.

   Asegúrese de que DQ_AGORA_IDENTITY_TOKEN esté configurado en su entorno, luego ejecute el siguiente comando en macOS o Linux:

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

   Para instalar una versión específica, incluya esto en el comando bash:

   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. Abra una nueva terminal y verifique que maestro --version muestre la versión de Axe DevTools.

   maestro --version

Inicio rápido

1. Cree un archivo de flujo.

   Cree un archivo llamado accessibility-check.yaml y agregue el fragmento de código a continuación:

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

   Reemplace com.example.myapp con el nombre del paquete de su aplicación (Android) o el ID del paquete (iOS), y complete su clave de API de Axe DevTools Mobile e ID de proyecto del Axe Developer Hub.

2. Ejecute el flujo.

   Para iOS:

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

   Para Android:

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

   Refiriéndose al archivo de flujo que acaba de crear, Maestro lanzará su aplicación, iniciará una sesión de escaneo de Axe DevTools y ejecutará un escaneo de accesibilidad en la pantalla actual. Los resultados se cargan automáticamente en el Axe Developer Hub.

   note

   El 'DEVICE_ID' es un identificador único que Maestro utiliza para las máquinas en las que ejecuta sus pruebas. Visite la documentación de Maestro para aprender cómo encontrar el ID del dispositivo.

Usar variables de entorno para credenciales

No se recomienda codificar claves de API en archivos YAML. En su lugar, utilice la interpolación de variables de Maestro con variables de entorno.

Nota: Maestro solo inyecta automáticamente variables de entorno de shell que comienzan con MAESTRO_. Use el prefijo MAESTRO_ para cualquier variable que desee disponible en sus flujos YAML.

Agregue lo siguiente a su perfil de shell (por ejemplo, ~/.zshrc o ~/.bashrc):

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

Luego, refiérase a esto en su YAML:

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

Alternativamente, pase estas variables de entorno en línea al ejecutar:

Para iOS:

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

Para Android:

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

Referencia de comandos

axeStartScanSession

Inicie una sesión de escaneo de Axe DevTools, proporcionando las credenciales necesarias a axeStartScanSession. Llame a esto una vez, antes del primer axeScan en su flujo.

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

axeScan

Use axeScan para ejecutar un escaneo de accesibilidad en la pantalla actual. Si axeStartScanSession fue llamado anteriormente en el flujo, los resultados se cargan en Axe Developer Hub.

# Simple form (all defaults):
- axeScan

Ejemplos

Escanear una sola pantalla

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

Escanear múltiples pantallas en un solo flujo

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

Escanear con una URL personalizada de la cuenta de Axe

Para implementaciones locales o en nube privada de Axe DevTools, se requiere un axeAccountURL:

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

Escaneo de accesibilidad no bloqueante

Use optional: true con axeScan para ejecutar el escaneo sin que falle el flujo general si el escaneo encuentra un error:

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"

Combinar escaneos de accesibilidad con pruebas de UI

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"

Visualización de resultados

Después de completar un escaneo, los resultados están disponibles en Axe Developer Hub, un lugar central donde todo tu equipo puede ver y gestionar los problemas de accesibilidad encontrados en tu aplicación. Los problemas en Developer Hub están categorizados por severidad y por las directrices WCAG, para que tu equipo pueda priorizar la remediación de los problemas.

Solución de problemas

Si encuentras problemas, intenta lo siguiente.

• “Comando no encontrado: maestro”

  Abre un nuevo terminal después de la instalación, o ejecuta:

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

• Errores de versión de Java

  Axe DevTools Mobile Maestro requiere Java 17 o superior. Comprueba tu versión de Java:

  java -version

  Si tu versión es inferior a 17, instala un JDK más reciente (por ejemplo, vía Adoptium).