iOS Mobile Accessibility Testing - Installation and Usage

In this article, we will guide you through the installation and usage of the Mobile Accessibility Testing tool, a macOS command-line utility for auditing the accessibility of iOS apps. First, we will install the required dependencies (XCode, Appium, and the tool itself), and then cover how to audit an iOS app running in a simulator or on a real device.

Install XCode

XCode, Apple’s development environment, as well as the XCode developer tools, must be installed to run iOS simulators and connect to real devices.

Install XCode from the App Store, then open a terminal and run:

xcode-select --install

Install Appium v2

The Siteimprove Mobile Accessibility Testing tool uses Appium v2 along with the XCUITest ("XCode UI Testing") driver to inspect elements of an app running on a simulator or a connected device.

To install Appium, refer to the official instructions as well as npm installation guidance.

After installing Appium, install the XCUITest driver by running:

appium driver install xcuitest

You are now ready to run Appium in a terminal:

appium

This will start an Appium server, which will wait for incoming connections. When you run the Siteimprove Mobile Accessibility Testing tool later, it will connect to this Appium server.

If the server starts successfully and loads the XCUITest driver, you should see output like:

[Appium] XCUITestDriver has been successfully loaded in ---s
[Appium] Appium REST http interface listener started on http://0.0.0.0:4723

Install the Siteimprove Mobile Accessibility Testing, for iOS

Download the Siteimprove Mobile Accessibility Testing tool from the Siteimprove Intelligence Platform under:

Accessibility > Mobile Accessibility Testing > Get Started

Not sure whether to choose "Apple Silicon" or "Intel-based Macs"?

Open About This Mac by clicking the Apple icon in the top-left corner. If the “Chip” says Intel, you are using an Intel-based Mac. If it says Apple (e.g., “Apple M3”), you are using an Apple Silicon Mac.

The download is an archive (si-a11y.tar.gz) that contains the executable and license files. You may want to move it to a new folder before extracting.

Extract it by running:

tar -xzf si-a11y.tar.gz

Confirm that it works by running

./si-a11y version

This should print something like

AppA11y.AppSnap 1.0.0..

Optionally add it to your PATH:

# eg. by adding it the bin folder (this might require `sudo`):
mv si-a11y /usr/local/bin
# then you can use it from anywhere
si-a11y version

Building Appium capabilities

Before auditing your app, you need to define a set of Appium capabilities to allow Appium to connect to your device or simulator using the XCUITest driver.

At a minimum, to connect to a local simulator, you can use:

{
  "appium:automationName": "XCUITest",
  "platformName": "iOS",
  "appium:deviceName": "<device name>"
}

• appium:automationName must be set to "XCUITest" — this is the only driver currently supported by the Siteimprove Mobile Accessibility Testing tool.
• appium:deviceName should match the name of a running simulator (e.g., "iPhone 15").

To list available simulators, run:

xcrun simctl list devices

Note: This works only if you have iOS simulators installed in XCode.

To connect to a real device, follow the Appium XCUITest driver documentation.

To help build and test capability sets, you can use the open-source Appium Inspector.

Audit an app

You will need a Siteimprove API key and associated API username to audit your flow and generate an App Report. These credentials can be managed within the Siteimprove Intelligence Platform under: 

Settings > Integrations > API > API keys.

You can now execute the si-a11y tool to run an audit, pointing it to a file containing your Appium capabilities and providing your Siteimprove API credentials as environment variables:

SI_USER_NAME=example@siteimprove.com SI_API_KEY=<API key> ./si-a11y interactive --capabilities caps.json --app-name "Example app" --flow-name "Example flow"

Running the checker in interactive mode allows you to capture multiple UI states within a single flow.

• Once the tool connects to Appium, press Enter at any time to collect the current screen’s UI state and screenshot.
• When done, press Ctrl + D to submit the flow for auditing.

You will receive a summary and a link to the App Report with detailed results.

To audit a single screen instantly with no user interaction, you can use snapshot mode.

To explore available options and commands:

./si-a11y –help
./si-a11y interactive –help
./si-a11y snapshot --help

Recommended capabilities and settings

The XCUITest setting snapshotMaxDepth can limit how much of your UI is visible to the Siteimprove Mobile Accessibility Testing. If your app has deeply nested views, consider increasing this value from the default of 50. It can be set through the capabilities file like so:

{
  // ... rest of your capabilities
  "appium:settings[snapshotMaxDepth]": 75
}

Using the XCUITest setting pageSourceExcludedAttributes might obscure important information from the Siteimprove Mobile Accessibility Testing.

Using the universal-xml Appium plugin is not compatible with Mobile Accessibility Testing.

Siteimprove Mobile Accessibility Testing currently only supports the XCUItest driver.