Using ATX and WebDriverAgent for iOS Automation with Python

Preface

iOS automation frameworks are limited, especially for black‑box testing. Apart from Apple's UIAutomation, the newer WebDriverAgent (WDA) released by Facebook offers an HTTP‑based protocol, but the client library must be implemented manually. We have created a pure‑Python WDA client and published it at https://github.com/openatx/facebook-wda .

Many users are more interested in how to use it. Compared with Appium's iOS automation, ATX is considerably simpler.

ATX and Appium are unrelated; ATX is written in Python while Appium is primarily Node.js. ATX’s advantages include minimal dependencies, fast installation, ability to test third‑party apps (e.g., WeChat, NetEase News), easy updates via pip, built‑in image recognition, integrated test reports, and development by NetEase's game testing team, which provides timely Chinese support.

Installation

A macOS machine with Xcode is required; using a Hackintosh is discouraged due to extra troubleshooting effort.

WDA works on both simulators and real devices. Real iPhones do not need to be jail‑broken.

Install all macOS tools via Homebrew for convenience.

Follow the instructions on https://github.com/facebook/WebDriverAgent to install WebDriverAgent on the device until a "WebDriverAgent" app appears on the phone.

Open http://127.0.0.1:8100/inspector to view the inspector UI.

Install the Python library atx and other macOS dependencies as described in the GitHub guide https://github.com/codeskyblue/AutomatorX .

Before testing, switch the input method to the system default English keyboard; third‑party keyboards (e.g., certain Chinese input methods) are not supported.

Script Writing

First obtain the target app's bundle_id , e.g., using ideviceinstaller -l .

com.netease.cloudmusic, "464", "NetEase Cloud Music"

A simple script to verify that WDA is working:

# coding: utf-8
import atx
d = atx.connect('http://localhost:8100', 'com.netease.cloudmusic')
print d.status()

Replace localhost:8100 with the actual device IP and port when using a real phone.

The following script logs into NetEase Cloud Music and then logs out:

Open NetEase Cloud Music.

Log in with a NetEase account.

Enter username and password, confirm login.

Navigate to account settings and locate the logout button.

Tap logout and confirm.

Corresponding code (with line numbers for reference):

1  import atx
2  d = atx.connect('http://localhost:8100', platform='ios')
3  d.start_app('com.netease.cloudmusic')
4  d(text='网易邮箱').click()
5  d(xpath="//TextField").set_text("[email protected]\n")
6  d(xpath="//SecureTextField").set_text("password")
7  d(text='登录').click()
8  d(text='帐 号').click()
9  d(text='退出登录').scroll().click()
10 d(text='确定').click()

Notes:

Line 5 uses XPath because d(class_name="TextField") is not fully supported yet; the trailing newline hides the auto‑completion UI.

Line 8 requires a space inside the word "帐 号" to match the UI element.

Line 9 includes scroll() to make the logout button visible before clicking.

Test Report Generation

ATX integrates a reporting module. After the script, add the following code to enable reporting:

from atx.ext.report import Report
rp = Report(d).patch_wda()

Running the script again creates a report directory containing index.html , which can be opened in a browser to view detailed test results (screenshots, logs, etc.).

Below are example screenshots from the generated report:

That concludes the introduction. If you intend to pursue automation seriously, further reading is recommended; the learning curve may have obstacles, but the satisfaction of successful automation is well worth the effort.