Getting Started with Maestro

Axe DevTools Mobile for Maestro brings built-in accessibility scanning to Maestro, powered by Axe DevTools for Mobile SDKs. When you run your UI test flows with it, you can easily invoke automated accessibility checks directly in your YAML with two commands: axeStartScanSession and axeScan.

Requires

• macOS or Linux — the installer requires a Unix shell.
  • macOS: supports both Android emulator and iOS simulator
  • Linux: supports Android emulator only (iOS simulators are macOS-only)
• Java 17+ — verify with java -version
• curl and unzip — pre-installed on macOS and most Linux distributions
• Android emulator or iOS simulator with your app installed
• Axe DevTools Mobile API key
• Axe Developer Hub Project ID

(Note: Windows support is coming soon.)

Installation

1. If you previously installed public Maestro via Homebrew, uninstall it first to avoid PATH conflicts:

   brew uninstall maestro

2. You will need an identity token from Deque's private Artifactory. If you do not have one, follow the steps in Getting Started with Deque's Private Artifactory.

   Ensure DQ_AGORA_IDENTITY_TOKEN is set in your environment, then run the following command on macOS or Linux:

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

   To install a specific version, include this in the bash command:

   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 a new terminal and verify maestro --version shows the Axe DevTools version.

   maestro --version

Quick Start

1. Create a flow file.

   Create a file called accessibility-check.yaml and add the code snippet below:

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

   Replace com.example.myapp with your app's package name (Android) or bundle ID (iOS), and fill in your Axe DevTools Mobile API key and Project ID from Axe Developer Hub.

2. Run the flow.

   For iOS:

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

   For Android:

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

   Referring to the flow file you just created, Maestro will launch your app, initialize an Axe DevTools scan session, and run an accessibility scan on the current screen. Results are uploaded to Axe Developer Hub automatically.

   note

   The 'DEVICE_ID' is a unique identifier Maestro uses for the machines you run your tests on. Visit Maestro's documentation to learn how to find the device ID.

Use Environment Variables for Credentials

Hard-coding API keys in YAML files is not recommended. Use Maestro's variable interpolation with environment variables instead.

Note: Maestro only auto-injects shell environment variables that start with MAESTRO_. Use the MAESTRO_ prefix for any variables you want available in your YAML flows.

Add the following to your shell profile (e.g., ~/.zshrc or ~/.bashrc):

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

Then reference these in your YAML:

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

Alternatively, pass these environment variables inline when running:

For iOS:

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

For Android:

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

Command Reference

axeStartScanSession

Initialize an Axe DevTools scan session, providing the necessary credentials to axeStartScanSession. Call this once, before the first axeScan in your flow.

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

axeScan

Use axeScan to run an accessibility scan on the current screen. If axeStartScanSession was called earlier in the flow, results are uploaded to Axe Developer Hub.

# Simple form (all defaults):
- axeScan

Examples

Scan a single screen

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

Scan multiple screens in one flow

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

Scan with a custom Axe Account URL

For on-premises or private cloud Axe DevTools deployments, an axeAccountURL is required:

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

Non-blocking accessibility scan

Use optional: true with axeScan to run the scan without failing the overall flow if the scan encounters an 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"

Combine accessibility scans with 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"

Viewing Results

After a scan completes, results are available in Axe Developer Hub - a central location where your whole team can view and manage accessibility issues found in your app. Issues in Developer Hub are categorized by severity and WCAG guidelines, so your team can prioritize issues for remediation.

Troubleshooting

If you encounter issues, try the following.

• "Command not found: maestro"

  Open a new terminal after installation, or run:

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

• Java version errors

  Axe DevTools Mobile Maestro requires Java 17 or higher. Check your Java version:

  java -version

  If your version is below 17, install a newer JDK (e.g., via Adoptium).