uiautomator2 使用指南大全

import importlib.metadata

print(importlib.metadata.version("uiautomator2"))

import uiautomator2 as u2

d = u2.connect()          # 只有一台设备时
print(d.info)

d = u2.connect("R58M123456A")       # adb devices 里显示的序列号
d = u2.connect_usb("R58M123456A")   # 同义函数

d = u2.connect()

import adbutils
import uiautomator2 as u2

dev = adbutils.device(transport_id=6)   # 需要 adbutils >= 2.9.1
d = u2.connect(dev)

d = u2.connect("192.168.1.20:5555")

d = u2.connect("R58M123456A", port=9009)

import uiautomator2 as u2

SERIAL = None          # 多设备时填 "adb devices" 中的序列号
d = u2.connect(SERIAL)

print("设备信息:", d.device_info)
print("屏幕尺寸:", d.window_size())

d.screen_on()          # 点亮屏幕
d.unlock()             # 简单上滑解锁（不处理密码/PIN）

# 打开系统设置；不传 activity 时内部用 monkey 启动
d.app_start("com.android.settings", stop=True)

# 中英文界面都尝试一下；找不到返回 False，不会抛异常
opened = d.xpath(
    "//*[@text='Network & internet' or @text='网络和互联网']"
).click_exists(timeout=10)
print("进入网络设置:", opened)

d.screenshot("settings.png")
print("当前应用:", d.app_current())

d.press("back")
d.press("home")

print(d.info)            # UiAutomator 提供的信息
print(d.device_info)     # 基于 adb getprop 的信息
print(d.window_size())   # (宽, 高)
print(d.app_current())   # 当前前台应用
print(d.serial)          # 设备序列号
print(d.wlan_ip)         #  Wi-Fi IP，可能为 None

{
    "serial": "R58M123456A",
    "sdk": 34,
    "brand": "google",
    "model": "sdk_gphone64_arm64",
    "arch": "arm64-v8a",
    "version": 14,
}

info = d.app_current()
# {'package': 'com.android.settings', 'activity': '.Settings', 'pid': 12345}
print(info["package"], info["activity"])

# 等待指定 Activity 出现，返回 bool，默认等 10 秒
ok = d.wait_activity(".Settings", timeout=10)

w, h = d.window_size()
print(w, h)      # 例如 (1080, 2400)

d(text="Clock", className="android.widget.TextView")

d(text="设置").click()
d(text="设置", className="android.widget.TextView").click()

d(text="登录", className="android.widget.Button", clickable=True)

# 子节点（可跨层级）
d(className="android.widget.ListView").child(text="Bluetooth")

# 兄弟节点
d(text="Google").sibling(className="android.widget.ImageView")

# 在列表容器里按文本找子项；允许滚动查找
d(className="android.widget.ListView", resourceId="android:id/list") \
    .child_by_text("Wi-Fi", className="android.widget.LinearLayout",
                   allow_scroll_search=True)

# 按 contentDescription 找子项
d(className="android.widget.ListView").child_by_description("蓝牙")

# 按 instance 找子项
d(className="android.widget.ListView").child_by_instance(2)

d(className="android.widget.ListView", resourceId="android:id/list") \
    .child_by_text("Wi-Fi", className="android.widget.LinearLayout") \
    .child(className="android.widget.Switch") \
    .click()

d(text="Wi-Fi").right(className="android.widget.Switch").click()
d(text="Wi-Fi").left(className="android.widget.ImageView").click()
d(text="Wi-Fi").up(className="android.widget.TextView").click()
d(text="Wi-Fi").down(className="android.widget.TextView").click()

items = d(text="Add new")

print(items.count)      # 匹配数量
print(len(items))       # 同上
print(items[0].info)    # 第一个
print(items[-1].info)   # 最后一个

for view in items:
    print(view.info["text"], view.info["bounds"])

d.xpath("@com.example:id/login").click()
d.xpath("登录").click()
d.xpath("%登录%").click()
d.xpath("^.*(登录|登入)$").click()

# 按文本
d.xpath('//*[@text="登录"]').click()

# 按类名 + 文本
d.xpath('//android.widget.Button[@text="登录"]').click()

# 按 resource-id
d.xpath('//*[@resource-id="com.example:id/login"]').click()

# 包含文本
d.xpath('//*[contains(@text, "登录")]').click()

# 父节点 / 兄弟节点
d.xpath('//*[@text="用户名"]/..//android.widget.EditText').set_text("admin")
d.xpath('//*[@text="用户名"]/following-sibling::android.widget.EditText').set_text("admin")

# 第几个、最后一个
d.xpath('(//android.widget.ImageView)[1]').click()
d.xpath('(//android.widget.ImageView)[last()]').click()

# 组合条件
d.xpath('//*[@text="确定" and @clickable="true"]').click()

sl = d.xpath("@com.example:id/home_searchedit")

if sl.exists:
    sl.click()

if sl.wait(timeout=5):
    print("出现了")

el = sl.get(timeout=5)          # 返回元素
print(el.text, el.bounds)

sl.wait_gone(timeout=10)
sl.set_text("hello")

source = d.xpath.get_page_source()

els = source.find_elements('//android.widget.TextView')
for el in els:
    print(el.text, el.bounds)

# 点击第一个
d.click(*els[0].center())

# 复用同一份快照做多次查找（快照不会刷新）
ok = d.xpath("@com.example:id/ok", source=source)
if ok.exists:
    ok.click()

el = d.xpath("取消", source=source).match()
if el:
    el.click()

# 文本是 NFC，并且 resource-id 是 android:id/item
sel = d.xpath("NFC") & d.xpath("@android:id/item")
sel.get()

# 文本是 NFC 或 App 或 Content
sel = d.xpath("NFC") | d.xpath("App") | d.xpath("Content")
sel.get()

# 更复杂的组合
sel = (d.xpath("NFC") | d.xpath("@android:id/item")) & d.xpath("//android.widget.TextView")

# 立即判断，不存在就返回 False
if d(text="设置").exists:
    print("存在")

# 最多等 3 秒
if d(text="设置").exists(timeout=3):
    print("3 秒内出现了")

# 等待出现 / 等待消失
appeared = d(text="设置").wait(timeout=5)          # bool
gone = d(text="加载中").wait_gone(timeout=30)       # bool

# 等不到就抛 UiObjectNotFoundError
d(text="设置").must_wait(timeout=5)

if d.exists(text="设置"):
    ...

d(text="登录").click()                  # 默认最多等 wait_timeout（20 秒）
d(text="登录").click(timeout=5)         # 只等 5 秒
d(text="登录").click(offset=(0.5, 0.5)) # 相对元素左上角的比例，默认中心
d(text="登录").click(offset=(0, 0))     # 左上角
d(text="登录").click(offset=(1, 1))     # 右下角

# 存在才点，返回是否点击成功；默认 timeout=0，即不等待
clicked = d(text="跳过").click_exists()
clicked = d(text="跳过").click_exists(timeout=3)

# 反复点，直到元素消失
gone = d(text="引导层").click_gone(maxretry=5, interval=1.0)

d(text="文件").long_click()                 # 默认按 0.5 秒
d(text="文件").long_click(duration=1.0)

# 原生 setText：直接把文本写进控件，速度快
d(className="android.widget.EditText").set_text("hello")
print(d(className="android.widget.EditText").get_text())
d(className="android.widget.EditText").clear_text()

# UiObject.send_keys 是 set_text 的别名，不是全局输入
d(className="android.widget.EditText").send_keys("hello")

# 拖到坐标 / 拖到另一个元素
d(text="卡片").drag_to(500, 1200, duration=0.5)
d(text="卡片").drag_to(text="目标区域", duration=0.5)

# 从元素中心向某个方向滑
d(text="卡片").swipe("left", steps=20)     # left / right / up / down
d(text="卡片").swipe("up", steps=10)

# 双指手势：两对起点、两对终点
d(text="图片").gesture((300, 800), (700, 800), (300, 400), (700, 400), steps=100)

# 双指捏合 / 放大
d(text="图片").pinch_in(percent=100, steps=50)
d(text="图片").pinch_out(percent=100, steps=50)

# fling：快速滑动（惯性）
d(scrollable=True).fling()                    # 垂直向前
d(scrollable=True).fling.vert.forward()
d(scrollable=True).fling.vert.backward()
d(scrollable=True).fling.horiz.toEnd()
d(scrollable=True).fling.horiz.toBeginning(max_swipes=1000)

# scroll：受控滚动
d(scrollable=True).scroll(steps=20)           # 垂直向前
d(scrollable=True).scroll.horiz.forward(steps=100)
d(scrollable=True).scroll.vert.toEnd()
d(scrollable=True).scroll.vert.to(text="Security")

info = d(text="设置").info
print(info["text"], info["className"], info["clickable"])
print(info["bounds"])          # {'left': .., 'top': .., 'right': .., 'bottom': ..}

lx, ly, rx, ry = d(text="设置").bounds()
x, y = d(text="设置").center()
x, y = d(text="设置").center(offset=(0, 0))   # 左上角

d(text="设置").screenshot().save("item.png")

d.click(500, 1200)
d.click(0.5, 0.5)                 # 屏幕中心（比例坐标）

d.double_click(500, 1200)
d.double_click(500, 1200, 0.1)    # 两次点击间隔 0.1 秒

d.long_click(500, 1200)
d.long_click(500, 1200, duration=1.0)

d.swipe(900, 1500, 200, 1500)              # 从右向左
d.swipe(0.9, 0.5, 0.1, 0.5, duration=0.3)  # 比例坐标 + 时长
d.swipe(900, 1500, 200, 1500, steps=30)    # 按步数控制速度

d.swipe_ext("left")                 # 手指左滑
d.swipe_ext("right", scale=0.8)     # 滑动距离为屏幕宽度的 80%
d.swipe_ext("up", scale=0.8)
d.swipe_ext("down")
d.swipe_ext("left", box=(0, 0, 1080, 800))   # 限定在某个区域内滑

from uiautomator2 import Direction

d.swipe_ext(Direction.FORWARD)          # 页面向下翻（手指上滑）
d.swipe_ext(Direction.BACKWARD)         # 页面向上翻
d.swipe_ext(Direction.HORIZ_FORWARD)    # 页面向右翻
d.swipe_ext(Direction.HORIZ_BACKWARD)   # 页面向左翻

d.drag(500, 500, 500, 1500)
d.drag(500, 500, 500, 1500, duration=1.0)

# 依次经过多个点（九宫格解锁常用）
d.swipe_points([(200, 500), (500, 500), (800, 500)], duration=0.2)

import time

d.touch.down(500, 500)
time.sleep(0.05)
d.touch.move(520, 520)
time.sleep(0.05)
d.touch.up(520, 520)

d.press("home")
d.press("back")
d.press("recent")          # 最近任务
d.press("enter")
d.press("delete")          # 或 "del"
d.press("volume_up")
d.press("power")

# 数字 keycode + meta
d.press(0x07, 0x02)        # KEYCODE_0 + META_ALT

d.long_press("home")            # 等价于 adb shell input keyevent --longpress HOME
d.keyevent("HOME")              # 走 adb shell input keyevent

d.screen_on()
d.screen_off()
print(d.info["screenOn"])

d.unlock()      # 亮屏 + 从左下往右上滑；不处理密码、PIN、图案

print(d.orientation)       # natural / left / right / upsidedown

d.orientation = "left"     # 或 "l"
d.orientation = "natural"  # 或 "n"

d.freeze_rotation()        # 冻结旋转
d.freeze_rotation(False)   # 取消冻结

d.open_notification()
d.open_quick_settings()

d.show_touch_trace()                                   # 打开
d.show_touch_trace(pointer_location=False, show_touches=False)  # 关闭

d.send_keys("Hello123")
d.send_keys("你好，世界", clear=True)   # 先清空再输入

d.clear_text()                          # 清空当前焦点输入框

d.send_action()              # 智能回车/搜索
d.send_action("search")      # go / search / send / next / done / previous
d.send_action("done")

print(d.current_ime())            # 例如 com.github.uiautomator/.AdbKeyboard
print(d.is_input_ime_installed())

d.set_input_ime()                 # 安装并切换（需要时会自动装 APK）
d.set_input_ime(False)            # 禁用辅助输入法

d.hide_keyboard()

d.clipboard = "hello"
d.set_clipboard("hello", "label")

print(d.clipboard)

d.screenshot("home.jpg")          # 保存到文件，返回 None
img = d.screenshot()              # 返回 PIL.Image
img.save("home.png")

# OpenCV 格式（需要 numpy + cv2）
import cv2
cv_img = d.screenshot(format="opencv")
cv2.imwrite("home_cv.jpg", cv_img)

# 多屏设备指定 display
d.screenshot("second.png", display_id=1)

xml = d.dump_hierarchy()
xml = d.dump_hierarchy(pretty=True)
xml = d.dump_hierarchy(max_depth=30)
xml = d.dump_hierarchy(compressed=True)
xml = d.dump_hierarchy(root_in_active=True)   # 只导出当前活动窗口根节点

print(d.last_toast)       # 最近一条 Toast 文本，没有则 None
d.clear_toast()

msg = d.toast.get_message(wait_timeout=5, default=None)
d.toast.reset()

# 不传 activity：内部用 monkey 启动
d.app_start("com.example.app", stop=True)

# 指定 activity：等价于 am start -n pkg/activity
d.app_start("com.example.app", ".ui.MainActivity")

# 启动并等待进程出现
d.app_start("com.example.app", ".ui.MainActivity", wait=True)

# 强制用 monkey（副作用：可能关闭系统旋转锁定）
d.app_start("com.example.app", use_monkey=True)

d.app_stop("com.example.app")      # am force-stop
d.app_clear("com.example.app")     # pm clear，会清空应用数据

# 停止所有正在运行的第三方应用（慎用）
d.app_stop_all(excludes=["com.example.keep"])

print(d.app_info("com.example.app"))
# {'versionName': '1.2.3', 'versionCode': 123}

print(d.app_list("-3"))            # 只列第三方应用
print(d.app_list("com.example"))   # 包名包含该串的应用
print(d.app_list_running())        # 正在运行的应用

pid = d.app_wait("com.example.app", timeout=15)
pid = d.app_wait("com.example.app", timeout=15, front=True)  # 等它到前台

d.app_install("/path/to/app.apk")
d.app_install("https://example.com/app.apk")

ok = d.app_uninstall("com.example.app")   # bool
d.app_uninstall_all(excludes=["com.example.keep"])

# Android 6+，自动授予运行时权限
d.app_auto_grant_permissions("com.example.app")

d.open_url("https://example.com")
d.open_url("myapp://detail?id=1")

with d.session("com.example.app") as sess:
    sess(text="登录").click()
    sess.xpath("//*[@text='首页']").wait(timeout=10)
# 退出 with 后自动停止应用

# 附加到已运行的应用（不强制停止；内部仍会执行一次启动）
sess = d.session("com.example.app", attach=True)

print(sess.running())
sess.restart()
sess.close()

d.settings["wait_timeout"] = 10.0      # 默认 20 秒
print(d.settings["wait_timeout"])

# 等价写法（旧接口，仍可用）
d.implicitly_wait(10.0)
print(d.implicitly_wait())

d.settings["operation_delay"] = (0.3, 0.5)   # 操作前 0.3s，操作后 0.5s
d.settings["operation_delay"] = 0.2          # 前后都 0.2s

d.settings["operation_delay_methods"] = ["click", "swipe", "drag", "press"]

# 等页面出现
d(text="首页").wait(timeout=10)

# 等加载消失
d(className="android.widget.ProgressBar").wait_gone(timeout=30)

# 等 Activity
d.wait_activity(".MainActivity", timeout=10)

# 等应用进程
d.app_wait("com.example.app", timeout=20, front=True)

import time

def wait_until(predicate, timeout=10.0, interval=0.5, message="等待超时"):
    deadline = time.time() + timeout
    while time.time() < deadline:
        if predicate():
            return True
        time.sleep(interval)
    raise TimeoutError(message)

wait_until(lambda: d(text="完成").exists, timeout=15)

import time

def click_with_retry(selector, times=3):
    for i in range(times):
        if selector.click_exists(timeout=3):
            return True
        time.sleep(1)
    raise RuntimeError("点击失败")

click_with_retry(d(text="提交"))

# 注册规则（此时还没有开始监控）
d.watcher.when("跳过").click()
d.watcher.when("同意").click()
d.watcher.when("@com.example:id/close").click()

# 只有“立即更新”和“取消”同时存在时才触发
d.watcher.when("立即更新").when("取消").click()

# 启动后台监控，每 2 秒检查一次
d.watcher.start(interval=2.0)

# 主流程
d.xpath("//*[@text='开始使用']").click()

# 结束时停止
d.watcher.stop()
d.watcher.reset()

d.watcher("close_ad").when("@com.example:id/close").click()
d.watcher.start()
...
d.watcher.remove("close_ad")

d.watcher.when("//*[@text='更新']").call(lambda d: d.press("back"))
d.watcher.when("确定").call(lambda selector: selector.get_last_match().click())

with d.watch_context(builtin=True) as ctx:
    ctx.when("同意").click()
    ctx.wait_stable()

r = d.shell("dumpsys battery")
print(r.output)       # 字符串输出
print(r.exit_code)    # 退出码

r = d.shell(["pm", "list", "packages", "-3"])
print(r.output)

# 设置超时（秒）
d.shell("ping -c 4 8.8.8.8", timeout=10)

d.push("local.txt", "/sdcard/Download/local.txt")
d.push("local.txt", "/sdcard/Download/")          # 保留文件名
d.push("run.sh", "/data/local/tmp/", mode=0o755)  # 同时设置权限

import io
d.push(io.BytesIO(b"hello"), "/sdcard/Download/a.txt")

d.pull("/sdcard/Download/a.txt", "a.txt")

print(d.adb_device.getprop("ro.product.model"))
d.adb_device.install("/path/to/app.apk")
print(d.adb_device.app_current())

# 同步读写
d.adb_device.sync.push("/local/a.txt", "/sdcard/a.txt")
d.adb_device.sync.pull("/sdcard/a.txt", "/local/a.txt")

d.shell("screenrecord --time-limit 10 /sdcard/demo.mp4")
d.pull("/sdcard/demo.mp4", "demo.mp4")

d.debug = True
print(d.info)

import logging
import uiautomator2 as u2

u2.enable_pretty_logging(logging.INFO)   # 默认是 DEBUG
logger = logging.getLogger("uiautomator2")

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)

print(d.dump_hierarchy(pretty=True))

print(d.dump_hierarchy(pretty=True, max_depth=20))

print(d.jsonrpc.getConfigurator())

d.jsonrpc.setConfigurator({
    "waitForIdleTimeout": 100,
    "waitForSelectorTimeout": 0,
})

d.stop_uiautomator()      # 停止
d.start_uiautomator()     # 启动
d.reset_uiautomator()     # 停止 + 启动

d.info
d.xpath("//*[@text='设置']").exists

from uiautomator2.exceptions import (
    UiObjectNotFoundError,
    XPathElementNotFoundError,
    SessionBrokenError,
)

try:
    d(text="登录").click(timeout=5)
except UiObjectNotFoundError:
    d.screenshot("login_not_found.png")
    print(d.dump_hierarchy(pretty=True))
    raise

try:
    d.xpath("//*[@text='完成']").click(timeout=5)
except XPathElementNotFoundError:
    print("没找到完成按钮")

try:
    run_case(d)
finally:
    d.screenshot("final.png")

def test_login(d):
    d.app_start("com.example.app", stop=True)
    d(text="我的").click(timeout=10)          # 等页面
    d(text="登录").click()
    d(className="android.widget.EditText", instance=0).set_text("user")
    d(className="android.widget.EditText", instance=1).set_text("pass")
    d(text="提交").click()
    assert d(text="欢迎").wait(timeout=10)