Auto Scan

Overview

Hooking into standard XCUITest gestures, Auto Scan captures and scans every screen your test suite interacts with, without the need to add individual scan calls, imports, or modifications to your tests.

How it works

1. When the test bundle starts, Auto Scan loads axe_config.json and begins observing interactions
2. After each supported interaction, Auto Scan captures the current screen
3. When the test bundle finishes, Auto Scan processes your results, saves a JSON result for each screen - along with a summary and an HTML report - to AxeDevToolsMobileResults/, and optionally uploads results to Developer Hub

Getting Started

1. Create axe_config.json:

{
  "axeAutoScanMode": true,
  "axeAppBundleId": "com.example.myapp",
  "axeMobileApiKey": "<API_KEY>",
  "axeProjectId": "<PROJECT_ID>"
}

2. Add axe_config.json to UI test target bundle in Xcode (Project Navigator > Add Files > Check the UI test target)
3. Add axe_config.json to .gitignore
4. Run tests normally

Example Code

The snippet below is a standard XCUITest, with no Auto Scan-specific code:

import XCTest

class MyAppUITests: XCTestCase {
    let app = XCUIApplication()

    override func setUpWithError() throws {
        app.launch()  // triggers initial capture
    }

    func testSettings() throws {
        app.buttons["Settings"].tap()  // triggers capture
    }
}

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

Auto Scan generates a few different files at the end of each test run, including a self-contained HTML report that includes screenshots, view hierarchy data, and detailed issue information. All files are saved to the AxeDevToolsResults directory.

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.

Configuration Reference

Properties

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.

Both pieces below are required:

Test setup:

override func setUpWithError() throws {
    let app = XCUIApplication()
    app.launchArguments.append("-DisableAnimations")
    app.launch()
}

App launch path (AppDelegate or @main):

if ProcessInfo.processInfo.arguments.contains("-DisableAnimations") {
    UIView.setAnimationsEnabled(false)
}

The launch argument passes the flag to the app process. The app-side check acts on it. Neither works alone.

Note: UIView.setAnimationsEnabled(false) does not cover SwiftUI-native animations (withAnimation {}). SwiftUI apps may need additional handling.

Troubleshooting

• No results? Verify axe_config.json is included in the UI test target bundle. Check Target Membership in XCode's File Inspector.
• 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.