Setup

Link to Setup copied to clipboard

Get setup for accessibility testing in iOS and Android with axe DevTools Mobile in Appium.

Requires:

Your tests running against Appium version 2.0 or above

API Key for the axe DevTools Mobile Dashboard

Use of UiAutomator2 or XCUITest Driver

Node.js v.20 or above

As a driver for Appium, axe DevTools Mobile is designed to integrate seamlessly into your existing Appium tests for iOS and Android, no matter the language of Appium's client libraries!

First Time Setup

Configure npm for accessing axe DevTools Mobile

axe DevTools Mobile for Appium is available through Deque's Artifactory as an npm package. Follow our guide for setting up your npm registry to access axe DevTools Mobile.

Install the Drivers

Install the required drivers to your Appium instance through the command line:

axe XCUITest Driver for iOS Testing

appium driver install --source=npm @axe-devtools/axe-appium-xcuitest-driver

If you need to uninstall at any time, you can uninstall through the command line:

appium driver uninstall axexcuitest

axe UIAutomator2 Driver for Android Testing

appium driver install --source=npm @axe-devtools/axe-appium-uiautomator2-driver

If you need to uninstall at any time, you can uninstall through the command line:

appium driver uninstall axeuiautomator2

Optional Configure iOS Driver for Real Devices

Running Appium tests on real iOS devices requires some additional setup. Please follow the XCUITest Driver Real Device Configuration guide from Appium to get started. The open-wda command isn't currently supported with axe XCUITest Driver, but will be in a future release. For now, the default path to the WebDriverAgent Xcode project is as follows:

~/.appium/node_modules/@axe-devtools/axe-appium-xcuitest-driver/node_modules/@axe-devtools/axe-appium-webdriveragent/WebDriverAgent.xcodeproj

Start Accessibility Testing Through Appium

Start the Appium server as normal:

appium

Configure Your Tests

From your Appium automation scripts, add the capabilities required for axe DevTools Mobile for the platform under test:

Required Android Capability:

Name	Type	Description
automationName	`String`	Set to 'AxeUiAutomator2' to utilize the driver with axe DevTools Mobile embedded to run accessibility scans.
appPackage	`String`	The application package of the app under test. Note `appPackage` is a part of the UiAutomator2 driver, you may already have it set.

Required iOS Capability:

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 `bundleId` is a part of the XCUITest driver, you may already have it set.

Scan for Accessibility Issues

Now with the Appium server running, you're ready to start testing.

The accessibility scan can be activated at any point in your tests. When you're ready to kick off an accessibility scan, call the execute script API.

execute_script("mobile: axeScan", settings)

Input

Param	Type	Description
Settings	`Object`	Includes the required configurations for axe DevTools Mobile. (See Required Keys in Settings).

Required Keys in Settings

Key	Type	Description
apiKey	`String`	Required by Deque to provide access to authorized users. Access your axe DevTools Mobile API Key in the axe Account portal.

Optional Keys in Settings

Key	Type	Description
scanName	`String`	Provide a customized scan name to better identify scans within the dashboard.
tags	`[String]`	Provide an array of strings to apply to scans as tags. We recommend using tags to help you locate and group essential scans. Tagged scans are available to other team members.

tip

You may consider adding a utility function to your testing script as a central place to initiate an accessibility scan.

Output

By default your accessibility results are available on the axe DevTools Mobile Dashboard. If you would like to analyze your results in your tests, the executeScript method has two potential outputs:

A result object: export a scan from the dashboard to get the full JSON structure available to you.

{
   "axeRuleResults": [{
      "ruleSummary": "This view's accessibility path (or VoiceOver focus box) encapsulates its own visual on-screen frame.",
      "standard": "Best Practice",
      "status": "PASS",
      "props": {
         "accessibilityPath": {
            "right": 204,
            "bottom": 293,
            "top": 161,
            "left": 0
         },
         "className": "UIAccessibilityBackButtonElement",
         "isAccessibilityFocusable": true,
         "elementType": "button",
         "boundsInScreen": {
            "top": 161,
            "bottom": 293,
            "left": 0,
            "right": 204
         },
         "elementOffScreen": {
            "isOffScreen": false,
            "percentOffScreen": 0
         }
      },
      "isVisibleToUser": true,
      "ruleId": "A11yElementFocusBox",
      "axeViewId": "84926466349703185238156",
      "experimental": false,
      "impact": 1
   }...]
...

An error object with a message:

{ "axeError": { "message": "User is not authenticated." } }

JavaScript Example:

const result = await driver.execute('mobile: axeScan', settings)

if (result.axeError) {
  console.log('error: ' + result.axeError.message)
} else {
  console.log('no error')
  // do results validation here
}

After the Scan

Once the scan has finished it is automatically published to the axe DevTools Mobile Dashboard.

That's it! Now would be the time to navigate to the next screen in your script and take another scan.