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 plugin 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!

note

Rules have been developed and tested in the below platform and view configurations:

iOS: UIKit, React Native, .NET MAUI
Android: XML, React Native, .NET MAUI

Support for other view types are being actively worked on and will be a part of an upcoming release.

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 Plugin

Install the plugin to your Appium instance through the command line:

appium plugin install --source=npm @axe-devtools/appium-plugin

If you need to uninstall at any time, or in preparation for a newer version, you can uninstall through the command line:

appium plugin uninstall axeDevToolsMobile

Start Accessibility Testing Through Appium

Start the Appium server with axe DevTools Mobile by running the command:

appium --use-plugins=axeDevToolsMobile

You should see axeDevToolsMobile with an Active status:

[Appium] Available plugins:
[Appium]   - axeDevToolsMobile@1.0.0 (ACTIVE)

Configure Your Tests

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

Required Android Capability:

Name	Type	Description
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
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 and plugin running, you're ready to start testing.

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

executeScript("axe:Scan", Settings)

Input

Param	Type	Description
Settings	`Object`	Includes the required configurations for axe DevTools Mobile. (See Required Keys in Settings).
PageSource	`String`	Optional: If you've already grabbed the PageSource for the current screen, you can provide it to axe DevTools Mobile without incurring that query cost again. Note: If you find that the screenshot and results are not matching in the dashboard, the PageSource may be stale and shouldn't be used.

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.

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. Note this exported scan will not include issue counts.

{ 
  //...
  "pass": {"count": 8}, 
  "fail": { "count": 7, "critical": 3, "serious": 0, "moderate": 4, "minor": 0 },
  "needsReview": { "count": 12, "critical": 0, "serious": 6, "moderate": 0, "minor": 6 },
  "ignored": { "count": 0 }

An error object with a message

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

JavaScript Example:

 const result = await driver.execute('axe:scan', 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.