Introduction
Python-uiautomator2 is an open-source automation testing tool specifically designed for testing native Android applications.
Supported Platforms and Languages
Python-uiautomator2 wraps Google's built-in uiautomator2 testing framework, providing convenient Python interfaces. It allows testers to write Python test code directly on a PC to operate mobile applications, enabling automation and significantly improving the efficiency of writing automation code.
Working Principle
The following image was created using Windows Paint software
As shown in the diagram, python-uiautomator2 consists of two main components: a Python client and a mobile device.
- Python client: Runs scripts and sends HTTP requests to the mobile device
- Mobile device: Runs an HTTP service that wraps uiautomator2, parsing received requests and converting them into uiautomator2 commands
The entire process:
- Install
atx-agent(daemon) on the mobile device, which then starts the uiautomator2 service (listening on port 7912 by default) - Write and execute test scripts on the PC (equivalent to sending HTTP requests to the mobile device's server)
- The mobile device receives HTTP requests from the PC via WiFi or USB and executes the specified operations
Installation
- Python 2 or Python 3 (you can also try using the Android Python client: QPython)
- Mobile device
Environment Setup
Install adb
If you can execute adb devices from the command line, skip this step. Download Android Platform Tools from the official Google website https://developer.android.com/studio/releases/platform-tools.html, extract it, and add the directory containing adb.exe to your system's PATH.
Install python-uiautomator2
pip install --pre -U uiautomator2
Install atx-agent on the device
First, connect the device to the PC and ensure it can be detected by adb devices.
# Download atx-agent from GitHub and push it to the phone. Install the package named `com.github.uiautomator` on the phone<br></br>$ python -m uiautomator2 init<br></br>success<br></br>
A "success" message indicates that atx-agent initialization was successful.
Application and Operations
Using uiautomator2
- Configure device parameters to specify which phone to operate
- Capture UI elements of the application to identify specific controls
- Perform operations on the captured elements, such as clicking or entering parameters
Configure Device Parameters
Python-uiautomator2 connects to mobile devices in two ways: via WiFi or USB. Each method has its advantages and disadvantages. WiFi is most convenient as it eliminates the need for a cable, while USB can be used when the PC and phone are on different network segments.
- Using WiFi connection
Obtain the phone's IP address and ensure the computer can ping the phone. The phone's IP can be found in Settings > WiFi settings. For example, if the phone's IP is 192.168.0.100, the connection code is:
import uiautomator2 as u2<br></br>device = u2.connect('192.168.0.100')<br></br>
- Using USB connection
The phone's serial number can be obtained via adb devices. Assuming the serial number is 123456f, the connection code is:
import uiautomator2 as u2<br></br>device = u2.connect_usb('123456f')<br></br>
Capture UI Elements
Although the Android SDK's built-in tool uiautomatorviewer.bat is tempting, it conflicts severely with uiautomator2 and cannot run simultaneously. Inspired by the uiautomatorviewer interface, I created weditor, which uses python-uiautomator2's two interfaces screenshot and dump_hierarchy to avoid these conflicts.
Note: weditor is still under development and its features may differ from what's described here.
Installation: pip install --pre weditor
Usage: First run python -m weditor, which will automatically open a web page at http://atx.open.netease.com (Note: this URL only provides a frontend, while the python -mweditor command opens a local HTTP interface that the frontend communicates with)
The following is a screenshot of the web page
Key points:
Ignore iOS and Neco options, and directly select Android. The input field can contain the device's IP or serial number, consistent with the Configure Device Parameters section above. After clicking Connect, a green leaf should appear if everything is normal.
When the page refreshes, click the blue Reload button to refresh.
Element Location Methods
- ResourceId location:
device(resourceId="com.smartisanos.clock:id/text_stopwatch").click() - Text location:
device(text="Stopwatch").click() - Description location:
device(description="..").click() - ClassName location:
device(className="android.widget.TextView").click()
XPath location is not supported. I initially planned to add support, but found it unnecessary as the same functionality can be achieved with other methods, albeit with slightly longer code.
Element Operations
# click<br></br>device(text="Settings").click()<br></br><br></br># long click<br></br>device(text="Settings").long_click()<br></br><br></br># wait for element to appear<br></br>device(text="Settings").wait(timeout=10.0)<br></br>
Nine-grid unlock: Previously covered in an article https://testerhome.com/topics/11034
Chinese Character InputIf you can locate the element, you can directly input Chinese using set_text
device(text="Settings").set_text("你好")<br></br>
If the element cannot be located, use the send_keys method and switch the input method
device.set_fastinput_ime(True)<br></br>device.send_keys("你好 Hello")<br></br>device.set_fastinput_ime(False) # Turn off input method when done<br></br>
Screenshot: device.screenshot("home.jpg")Get layer information: xml = device.dump_hierarchy()