Auto Scan with the XCUITest Driver

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

Overview

Auto Scan automatically captures accessibility snapshots as you navigate through your iOS app. Instead of manually triggering scans on each screen, you start an auto scan session, interact with the app, and stop the session to generate a report.

tip

If you need more granular control in your tests, see Targeted Testing with Appium.

How it works

Start an auto scan session (with your credentials)
Navigate through your app — screens are scanned automatically
Stop the session — an HTML report is generated at ~/AxeDevToolsMobileResults/

Getting Started

Start the Appium server as normal:

appium

Configure Your Tests

From your Appium automation scripts, add the capabilities required for Axe DevTools Mobile.

Name	Type	Description
automationName	`String`	Set to 'AxeXCUITest' to utilize the driver with axe DevTools Mobile embedded to run accessibility scans.
bundleId	`String`	The bundle identifier of the app under test. Note that `bundleId` is a part of the XCUITest driver; you may already have it set.

Start Auto Scan

Before starting your test suite, start Auto Scan by calling the axeStartAutoScanSession API:

beforeAll(async () => { // Start auto scan 
await driver.executeScript('mobile: axeStartAutoScanSession', 
    [{ axeMobileApiKey: 'your-api-key',
    axeProjectId: 'your-devhub-project-id' 
    ... 
    }]); 
})

Stop Auto Scan

Just before the test suite finishes, call the axeStopAutoScanSession API to stop Auto Scan and aggregate and upload the results.

await driver.executeScript('mobile: axeStopAutoScanSession', []);

note

The code snippets above are using JavaScript. See Auto Scan Code Examples with XCUITest for more complete examples in multiple programming languages.

Interpreting Results

Console summary

A console summary similar to the following is printed when the test suite finishes:

----  Axe DevTools Mobile Accessibility Summary ----
Scan 1:
  Screen: HomeScreen
  Issues: 3
  Issues by rule:
    - ColorContrast: 2
    - TouchTargetSize: 1

Scan 2:
  Screen: SettingsScreen
  Issues: 0

Total Scans: 2
❌ Total Issues: 3
----------------------------------------------------

A clean run will show Axe Clean - 0 Issues Found 🎉 in the console.

Output files

When the Auto Scan session stops, an HTML report is generated at ~/AxeDevToolsMobileResults/. The report contains accessibility violations, passes, and recommendations for each screen captured during the session.

Auto Scan Support

Rules

Auto Scan runs the full Axe rule set with the exception of ScreenOrientation, SupportsDynamicType, and all experimental rules. Find detailed information about what we check for in the Rule Overview for iOS.

Developer Hub

Auto Scan automatically uploads your results to Axe Developer Hub. If you only want to save results locally, set axeUploadResults to false.

Offline Mode

If you don't have cloud credentials, use an offline license key instead:

// JavaScript example
await driver.execute('mobile: axeStartAutoScanSession', {
  axeOfflineLicenseKey: 'YOUR_OFFLINE_LICENSE_KEY'
});

// ... navigate through the app ...

await driver.execute('mobile: axeStopAutoScanSession', {});

Configuration Reference

Properties

| Parameter | Type | Required | Description | |---|---|---| | axeUploadResults | Boolean | Optional | Upload results to dashboard (default: true) | | axeMobileApiKey | String | Required* | API key for cloud-based scanning | | axeProjectId | String | Optional | Project ID for organizing results | | axeOfflineLicenseKey | String | Required* | License key for offline mode (alternative to cloud credentials) | | axeServerUrl | String | Optional | Axe DevTools Mobile server URL |

Provide either cloud credentials (axeMobileApiKey + axeProjectId+ optional axeServerUrl) or an axeOfflineLicenseKey.

Best Practices

Disable Animations

Get the most accurate and comprehensive results from Auto Scan by disabling animation. This will ensure screens are fully rendered when captured. Add the following under capabilities:

  capabilities: {
    // ...existing capabilities
    'appium:reduceMotion': true, // enables iOS "Reduce Motion" accessibility setting
  }

Troubleshooting

Seeing results locally, but not in Developer Hub? The upload to Developer Hub fails if the size of any one result file is greater than 20MB, though all the results are still saved locally and shown in the local HTML report.
Check logs. Look for AutoScan messages in the console.

What's Next?

You can view your results in Axe Developer Hub. Learn how to integrate Axe DevTools Mobile in your CI/CD pipeline. Using a cloud-based testing platform? You can still use Axe DevTools Mobile to look for accessibility issues: Integrate with Cloud Platforms.