uiautomator

This module is a Python wrapper of Android [uiautomator][] testing framework. It works on Android 4.1+ (API Level 16~30) simply with Android device attached via adb, no need to install anything on Android device.

from uiautomator import device as d

d.screen.on()
d(text="Clock").click()

Installation

$ pip install uiautomator

Pre-requirements

Install Android SDK, and set ANDROID_HOME environment to the correct path.
Enable ADB setting on device and connect your android device using usb with your PC.
Allow apps to install from unknown sources on device settings.

import uiautomator

If ANDROID_SERIAL is defined in environment, or there is only one device connected:
```
from uiautomator import device as d
```

Speficy the serial number when retrieving the device object

from uiautomator import Device

d = Device('014E05DE0F02000E')

Speficy the adb server host and port running on other computer

Although adb supports -a option since SDK 4.3, but now it has a bug on it. The only way to start adb server listenning on all interfaces instead of localhost, is adb -a -P 5037 fork-server server &
```
from uiautomator import Device

d = Device('014E05DE0F02000E', adb_server_host='192.168.1.68', adb_server_port=5037)
```

Notes: In below examples, we use d represent the android device object.

Basic API Usages

Key Event Actions of the device
Gesture interaction of the device
Screen Actions of the device

Watcher introduction

Handler introduction

Selector introduction

How to selector the Child and sibling UI object
Get the specific UI object status and its information
Perform the click action on the seleted UI object
Gesture action for the specific ui object

Basic API Usages

This part show the normal actions of the device through some simple examples.

Retrieve the device info

d.info

Below is a possible result:

{ u'displayRotation': 0,
  u'displaySizeDpY': 640,
  u'displaySizeDpX': 360,
  u'currentPackageName': u'com.android.launcher',
  u'productName': u'takju',
  u'displayWidth': 720,
  u'sdkInt': 18,
  u'displayHeight': 1184,
  u'naturalOrientation': True
}

Key Event Actions of the device

Turn on/off screen

# Turn on screen
d.screen.on()
# Turn off screen
d.screen.off()

Alternative method is:

# wakeup the device
d.wakeup()
# sleep the device, same as turning off the screen.
d.sleep()

Check if the screen is on or off

if d.screen == "on":  # of d.screen != "off"
    # do something in case of screen on
    pass
if d.screen == "off":  # of d.screen != "on"
    # do something in case of screen off
    pass

Press hard/soft key

# press home key
d.press.home()
# press back key
d.press.back()
# the normal way to press back key
d.press("back")
# press keycode 0x07('0') with META ALT(0x02) on
d.press(0x07, 0x02)

Next keys are currently supported:
- home
- back
- left
- right
- up
- down
- center
- menu
- search
- enter
- delete(or del)
- recent(recent apps)
- volume_up
- volume_down
- volume_mute
- camera
- power
You can find all key code definitions at Android KeyEvent.

Gesture interaction of the device

Click the screen
```
# click (x, y) on screen
d.click(x, y)
```

Long click the screen

# long click (x, y) on screen
d.long_click(x, y)

Swipe

# swipe from (sx, sy) to (ex, ey)
d.swipe(sx, sy, ex, ey)
# swipe from (sx, sy) to (ex, ey) with 10 steps
d.swipe(sx, sy, ex, ey, steps=10)

Drag

# drag from (sx, sy) to (ex, ey)
d.drag(sx, sy, ex, ey)
# drag from (sx, sy) to (ex, ey) with 10 steps
d.drag(sx, sy, ex, ey, steps=10)

Screen Actions of the device

Retrieve/Set Orientation

The possible orientation is:

natural or n
left or l
right or r
upsidedown or u (can not be set)

# retrieve orientation, it may be "natural" or "left" or "right" or "upsidedown"
orientation = d.orientation
# set orientation and freeze rotation.
# notes: "upsidedown" can not be set until Android 4.3.
d.orientation = "l" # or "left"
d.orientation = "r" # or "right"
d.orientation = "n" # or "natural"

Freeze/Un-Freeze rotation

# freeze rotation
d.freeze_rotation()
# un-freeze rotation
d.freeze_rotation(False)

Take screenshot

# take screenshot and save to local file "home.png", can not work until Android 4.2.
d.screenshot("home.png")

Dump Window Hierarchy

# dump the widown hierarchy and save to local file "hierarchy.xml"
d.dump("hierarchy.xml")
# or get the dumped content(unicode) from return.
xml = d.dump()

Open notification or quick settings

# open notification, can not work until Android 4.3.
d.open.notification()
# open quick settings, can not work until Android 4.3.
d.open.quick_settings()

Wait for idle or window update

# wait for current window to idle
d.wait.idle()
# wait until window update event occurs
d.wait.update()

Watcher

You can register watcher to perform some actions when a selector can not find a match.

When a selector can not find a match, uiautomator will run all registered watchers.

Click target when conditions match

d.watcher("AUTO_FC_WHEN_ANR").when(text="ANR").when(text="Wait") \
                             .click(text="Force Close")
# d.watcher(name) ## creates a new named watcher.
#  .when(condition)  ## the UiSelector condition of the watcher.
#  .click(target)  ## perform click action on the target UiSelector.

Press key when conditions match

d.watcher("AUTO_FC_WHEN_ANR").when(text="ANR").when(text="Wait") \
                             .press.back.home()
# Alternative way to define it as below
d.watcher("AUTO_FC_WHEN_ANR").when(text="ANR").when(text="Wait") \
                             .press("back", "home")
# d.watcher(name) ## creates a new named watcher.
#  .when(condition)  ## the UiSelector condition of the watcher.
#  .press.<keyname>.....<keyname>.()  ## press keys one by one in sequence.
#  Alternavie way defining key sequence is press(<keybname>, ..., <keyname>)

Check if the named watcher triggered

A watcher is triggered, which means the watcher was run and all its conditions matched.
```
d.watcher("watcher_name").triggered
# true in case of the specified watcher triggered, else false
```

Remove named watcher

# remove the watcher
d.watcher("watcher_name").remove()

List all watchers

d.watchers
# a list of all registered wachers' names

Check if there is any watcher triggered

d.watchers.triggered
#  true in case of any watcher triggered

Reset all triggered watchers

# reset all triggered watchers, after that, d.watchers.triggered will be false.
d.watchers.reset()

Remvoe watchers

# remove all registered watchers
d.watchers.remove()
# remove the named watcher, same as d.watcher("watcher_name").remove()
d.watchers.remove("watcher_name")

Force to run all watchers

# force to run all registered watchers
d.watchers.run()

Handler

The functionality of handler is same as Watcher, except it is implemented ourside of Android uiautomator. The most different usage between handler and watcher is, handler can use customized callback function.

def fc_close(device):
  if device(text='Force Close').exists:
    device(text='Force Close').click()
  return True  # return True means to break the loop of handler callback functions.

# turn on the handler callback function
d.handlers.on(fc_close)

# turn off the handler callback function
d.handlers.off(fc_close)

Selector

Selector is to identify specific ui object in current window.

# To seleted the object ,text is 'Clock' and its className is 'android.widget.TextView'
d(text='Clock', className='android.widget.TextView')

Selector supports below parameters. Refer to [UiSelector java doc](http://develope

Uiautomator

Install / Use

README