Auto Scan with the UIAutomator2 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 continuously monitors your Android app for accessibility issues as your tests run. Instead of scanning one screen at a time, it captures accessibility snapshots on every UI change and processes them all at the end.

tip

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

How it works

Start Auto Scan at the beginning of your test
Interact with your app — every screen change is captured automatically
Stop auto scan — results are processed and pulled to your local machine

Results are saved to build/AxeDevToolsMobileResults/ in your project directory.

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 'AxeUiAutomator2' to utilize the driver with Axe DevTools Mobile embedded for accessibility scans.
appPackage	`String`	The package name of the application under test. Note that `appPackage` is a part of the UiAutomator2 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 UIAutomator2 for more complete examples in multiple programming languages.

Interpreting Results

Console Summary

Once the test suite finishes, you can find a summary in the console window where the Appium server is running.

---- Axe DevTools Mobile Accessibility Summary ----
Scan 1:
  Screen: Home Page
  Issues: 6
  Issues by rule:
    - TouchSizeWcag: 3
    - LabelAtFront: 1
    - LabelInName: 1
    - FocusableText: 1
    
Scan 35:
  Screen: Wikipedia Alpha
  Issues: 5
  Issues by rule:
    - LabelAtFront: 1
    - LabelInName: 1
    - TouchTargetSpacing: 1
    - TouchSizeWcag: 1
    - ColorContrast: 1
    
Total Scans: 35
❌ Total Issues: 123
---------------------------------------------------

Output Files

When the Auto Scan session stops, an HTML report is generated at build/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 and all experimental rules (e.g. NestedActiveControl, NestedElementName, InaccessibleAction). Find detailed information about what we check for in the Rule Overview for Android.

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 the offline variant of the driver with an offline license key instead. Install @axe-devtools/axe-appium3-uiautomator2-driver-offline and pass in axeOfflineLicenseKey when starting the session.

Configuration Reference

Properties

Parameter	Type	Required	Description
`axeUploadResults`	boolean	No	Upload results to Developer Hub
`axeMobileApiKey`	string	Yes*	Your Axe DevTools Mobile API key
`axeProjectId`	string	No	Project ID for organizing results
`axeOfflineLicenseKey`	string	Yes*	License key for offline mode (alternative to cloud credentials)
`axeServerUrl`	string	No	Custom Axe server URL (for on-prem or private cloud)

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

Disable Animations

Get the most accurate and comprehensive results from Auto Scan by disabling animation. This will ensure screens are fully rendered when captured. If animations are not disabled, you may notice:

Duplicate scans that you believe should have been dropped
Scans with screenshots showing a transitory state
A significantly lower screen capture rate than you might be expecting

Add the following under capabilities:

capabilities: {
    // ...existing capabilities
    'appium:disableWindowAnimation': true, // disables window animations
  }

Troubleshooting

If you are not seeing scans show up in Developer Hub, you should check your logs for hints of what might be wrong or go through this checklist.

Make sure you are using the correct variable for your API/License Key and Project ID
Check the size of your output files. 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.

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. See Automated Testing on Cloud Platforms with Appium.