测试移动开发GUI 自动化【免费下载链接】uiautomator2Android Uiautomator2 Python Wrapper项目地址https://gitcode.com/gh_mirrors/ui/uiautomator2点击查看免费下载uiautomator2 的 XPath 扩展允许你用一行d.xpath(某文本).click()代替繁琐的坐标点击本文基于仓库内的 XPath 使用文档 和核心实现 uiautomator2/xpath.py完整讲解其工作原理、简化定位规则、XPathSelector/XMLElement/PageSource三层对象的全部可用操作以及滚动查找、弹窗监控等实战能力。读完你可以掌握如何写快速 XPath 表达式定位控件、如何处理元素延迟出现、如何在列表内滚动查找目标元素以及如何在自动化过程中自动消除干扰弹窗。工作原理dump_hierarchy lxml 两步走XPath 扩展的整体流程只有两步见 XPATH.md 的 How It Works 小节调用dump_hierarchy接口抓取当前界面的完整 UI 层级 XML每个控件的text、resource-id、class、bounds、content-desc等属性都在其中用lxml解析这份 XML执行 XPath 查询命中节点后取其中心坐标调用click等指令。目前lxml只支持 XPath 1.0XPath 2.0 的语法不可用。从源码结构看这个流程对应三层对象全部定义在 uiautomator2/xpath.py对象职责PageSource持有 hierarchy XML 字符串负责解析与查询find_elements是核心方法XPathSelector一次查询条件的封装负责存在性判断、等待、点击XMLElement命中的单个控件节点负责坐标、点击、滑动、截图等操作设备入口是d.xpath它是一个cached_property返回绑定设备实例的XPathEntry对象见 uiautomator2/init.pyXPathEntry.__call__即d.xpath(...)的落地实现返回XPathSelector。PageSource 的解析细节PageSource由d.dump_hierarchy()的返回值初始化XPathEntry.get_page_source()见 uiautomator2/xpath.py。它的关键处理在root属性中uiautomator2/xpath.py#L149-L154用lxml.etree.fromstring把 XML 解析成树遍历所有node节点把class属性如android.widget.TextView替换成节点 tag。这就是为什么你可以写//android.widget.TextView这种“类名即标签名”的表达式查询时find_elementsuiautomator2/xpath.py#L156-L158会注册 EXSLT 正则命名空间http://exslt.org/regular-expressions所以表达式里可以使用re:match()。弹窗监控原理hierarchy 里包含界面上所有元素包括弹窗按钮。假设有“跳过”“知道了”两个弹窗按钮真正要点的按钮是“播放”监控逻辑就是一个循环dump_hierarchy获取当前界面 XML检查“跳过”“知道了”是否存在存在就点击然后回到第 1 步检查“播放”是否存在存在就点击并结束否则回到第 1 步直到查找次数超标。这套“循环 dump 命中即点”的机制在新版中由 watcher 子系统承载uiautomator2/watcher.py。Watcher._watch_forever在后台线程里以固定 interval 反复执行run()每次 run 都会dump_hierarchy并对所有注册的条件逐一求值uiautomator2/watcher.py#L211-L231。watcher 还内置了一批常见干扰弹窗的自动点击规则例如“继续安装”“同意”“同意/确定”“Agree”“ALLOW”等uiautomator2/watcher.py#L36-L45上面这类安装确认弹窗“继续安装”/“拒绝”正是内置 watcher 规则的目标之一只要规则命中watcher 会在下一次检查周期自动点击“继续安装”让主流程无感通过。安装XPath 扩展内置于 uiautomator2 主包依赖lxml与Pillow截图裁剪使用安装即得pip3 install -U uiautomator2快速上手先启动目标应用再用 XPath 点击“私人FM”随后是几种元素定位写法以下摘自 XPATH.md 的 Simple Usage 小节import uiautomator2 as u2 def main(): d u2.connect() d.app_start(com.netease.cloudmusic, stopTrue) d.xpath(//*[text私人FM]).click() # # 高级用法元素定位 # # 开头 d.xpath(personal-fm) # 等价于 d.xpath(//*[resource-idpersonal-fm]) # 多条件定位类似于 AND d.xpath(//android.widget.Button).xpath(//*[text私人FM]) d.xpath(//*[text私人FM]).parent() # 定位到父元素 d.xpath(//*[text私人FM]).parent(android:list) # 定位到符合条件的父元素 # 使用 child 时不建议再叠加多条件 xpath容易混淆 d.xpath(android:id/list).child(/android.widget.TextView).click() # 等价于 # d.xpath(//*[resource-idandroid:id/list]/android.widget.TextView).click()说明链式.xpath(...)写法在源码中已标记 Deprecated推荐直接用运算符组合条件见后文“高级查找语法”.parent()/.parent(cond)的实现在 uiautomator2/xpath.py#L646-L668不带参数直接取 lxml 父节点带条件参数则从当前节点逐级向上回溯返回第一个满足条件的祖先.child(path)通过XPath.joinpath把子路径拼到基础表达式后面uiautomator2/xpath.py#L131-L134本质是生成一条完整的原生 XPath。XPath 简化定位规则为了少打字符uiautomator2 自定义了简化规则。这些规则由strict_xpath()函数统一转换成标准 XPathuiautomator2/xpath.py#L75-L112转换前后对照如下规则 1//开头代表原生 XPath原样透传d.xpath(//android.widget.Button) d.xpath(//*[contains(text, OK)])规则 2开头代表 resourceId 定位d.xpath(smartisanos:id/right_container) # 转换为 //*[resource-idsmartisanos:id/right_container]规则 3^开头代表正则表达式d.xpath(^.*道了) # 文档给出的等价形式为 //*[re:match(text(), ^.*道了)]从源码实现看^规则的转换结果比文档描述更宽它同时匹配text、content-desc、resource-id三个字段uiautomator2/xpath.py#L83-L86。规则 4%通配灵感来自 SQL LIKEd.xpath(知道%) # 匹配以“知道”开头 → //*[starts-with(text, 知道)] d.xpath(%知道) # 匹配以“知道”结尾 → //*[ends-with(text(), 知道)] d.xpath(%知道%) # 匹配包含“知道” → //*[contains(text, 知道)]源码中 starts-with / contains / ends-with 三种形式同样对text和content-desc两个字段同时生效。规则 Last裸文本同时匹配 text、description、resource-idd.xpath(搜索) # 转换为 //*[text搜索 or content-desc搜索 or resource-id搜索]这是最常用也最省事的写法绝大多数界面上的按钮/标签直接写可见文本即可命中。转换完成后strict_xpath还会用is_xpath_syntax_ok()基于etree.XPath的编译检查uiautomator2/xpath.py#L54-L59做语法校验表达式不合法时抛出XPathError(Invalid xpath)。XPathSelector 的全部操作sl d.xpath(com.example:id/home_searchedit)得到的是一个XPathSelector对象下称 sl完整操作集如下摘自 XPATH.md# 点击 sl.click() sl.click(timeout10) # 指定超时找不到抛出 XPathElementNotFoundError sl.click_exists() # 存在即点击返回是否点击成功 sl.click_exists(timeout10) # 最多等 10 秒 sl.match() # 不匹配返回 None否则返回 XMLElement # 等待元素出现返回 XMLElement el sl.wait() # 默认等待时间 el sl.wait(timeout15) # 等 15 秒找不到返回 None # 等待元素消失 sl.wait_gone() sl.wait_gone(timeout15) # 与 wait 类似但找不到直接抛 XPathElementNotFoundError el sl.get() el sl.get(timeout15) # 修改全局默认等待时间为 15 秒 d.xpath.global_set(timeout, 15) d.xpath.implicitly_wait(15) # 与上一行等价 print(sl.exists) # 是否存在bool sl.get_last_match() # 获取上次匹配的 XMLElement sl.get_text() # 获取组件文本 sl.set_text() # 清空输入框 sl.set_text(hello world) # 向输入框输入 hello world # 遍历所有匹配的元素 for el in d.xpath(//android.widget.EditText).all(): print(rect:, el.rect) # (x, y, width, height) print(center:, el.center()) el.click() # 点击 print(el.elem) # lxml 解析出的 Node print(el.text)几个值得注意的源码级细节等待机制是 0.2 秒轮询wait()内部循环调用exists每 0.2 秒重查一次页面直到命中或超过 deadlineuiautomator2/xpath.py#L449-L457wait_gone()逻辑相反。默认超时的真实取值文档写的是 10 秒但从源码结构看wait_timeout的设备级默认值是20.0 秒uiautomator2/settings.py#L15-L22XPathSelector._global_timeout在取不到配置时兜底也是 20.0uiautomator2/xpath.py#L370-L374。以源码为准。click 的实现先get()拿到元素再点其中心点uiautomator2/xpath.py#L487-L496单元断言可参见 tests/test_xpath.py——bounds[0,0][1080,100]的元素点击坐标被断言为(540, 50)。global_set(timeout, 15)的本质是调用implicitly_wait即写入d.wait_timeoutuiautomator2/xpath.py#L171-L184文档中同时建议的新写法是d.settings[wait_timeout] 15。set_text的两步动作先点击输入框获取焦点再调用send_keys输入uiautomator2/xpath.py#L444-L447。容错回调XPathSelector还支持fallback(fn)——元素找不到时执行自定义回调而不是抛异常uiautomator2/xpath.py#L358-L368。高级查找语法与|3.1 版本起支持用 Python 运算符组合多个查询条件__and__/__or__实现uiautomator2/xpath.py#L322-L334求值时在all()里对两组命中结果做集合交并uiautomator2/xpath.py#L383-L406# 查找 textNFC AND idandroid:id/item (d.xpath(NFC) d.xpath(android:id/item)).get() # 查找 textNFC OR idandroid:id/item (d.xpath(NFC) | d.xpath(App) | d.xpath(Content)).get() # 支持更复杂的组合 ((d.xpath(NFC) | d.xpath(android:id/item)) d.xpath(//android.widget.TextView)).get()XMLElement 的全部操作XPathSelector.get()返回的对象叫XMLElement文档示例与源码行为对照如下el d.xpath(com.example:id/home_searchedit).get() lx, ly, width, height el.rect # 左上角坐标 宽高 lx, ly, rx, ry el.bounds # 左上角与右下角坐标 x, y el.center() # 中心点 x, y el.offset(0.5, 0.5) # 同 center()按宽高百分比取点 el.click() # 点击 print(el.text) # 文本内容 print(el.attrib) # 原始属性 dict el.screenshot() # 控件截图整屏截图后按 bounds 裁剪 el.swipe(right) # left, right, up, down el.swipe(right, scale0.9) # 显式指定滑动距离比例 print(el.info) # 结构化的控件信息见下info的输出示例文档给出{ index: 0, text: , resourceId: com.example:id/home_searchedit, checkable: true, checked: true, clickable: true, enabled: true, focusable: false, focused: false, scrollable: false, longClickable: false, password: false, selected: false, visibleToUser: true, childCount: 0, className: android.widget.Switch, bounds: {left: 882, top: 279, right: 1026, bottom: 423}, packageName: com.android.settings, contentDescription: , resourceName: android:id/switch_widget }源码层面的补充说明坐标换算bounds从节点bounds[lx,ly][rx,ry]属性解析uiautomator2/xpath.py#L679-L689rect由 bounds 推出宽高offset(px, py)按宽高百分比取点。截图screenshot()先整屏d.screenshot()再crop(bounds)uiautomator2/xpath.py#L594-L599。info的整理逻辑布尔属性转成 Pythonbool、属性名转驼峰并追加childCount、className、结构化的boundsuiautomator2/xpath.py#L720-L743。还有long_click()按住约 400ms 的长按操作uiautomator2/xpath.py#L587-L592。get_xpath(strip_indexTrue)可拿到元素在页面树中的完整路径去掉索引方便调试定位uiautomator2/xpath.py#L551-L557。swipe 与 scroll 的区别el.swipe(direction, scale)在控件自己的 bounds 范围内滑动实际滑动轨迹由 uiautomator2/utils.py 的swipe_in_bounds计算——以控件边界框为基准scale 决定滑动距离占控件宽/高的比例起止点位于边中线上。注意源码签名的默认值是scale0.6uiautomator2/xpath.py#L601-L610文档示例中的 0.9 是显式传参。方向参数支持Direction枚举或字符串定义见 uiautomator2/_proto.py#L6-L18LEFT/RIGHT/UP/DOWN其中FORWARD up、BACKWARD down、HORIZ_FORWARD left、HORIZ_BACKWARD right即FORWARD表示“向下滑动看下面内容”。el.scroll(direction)与 swipe 不同它返回bool表示是否还能继续滚动实现原理是“滑动前后两次 dump比较控件子树里是否出现新节点”uiautomator2/xpath.py#L612-L632el.scroll(Direction.FORWARD) # 向下 el.scroll(Direction.BACKWARD) # 向上 el.scroll(Direction.HORIZ_FORWARD) # 水平向前 el.scroll(Direction.HORIZ_BACKWARD) # 水平向后 if el.scroll(forward): print(还可以继续滚动)这个返回值为scroll_to提供了“到底就停”的判据。滚动到指定位置scroll_toscroll_to用于“目标元素不在当前可视区时边滚边找”。文档提示该功能尚不算完全打磨比如无法独立检测是否已滑到底部并给出示例from uiautomator2 import connect_usb, Direction d connect_usb() d.scroll_to(下单) d.scroll_to(下单, Direction.FORWARD) # 默认向下滑动 # 其他方向BACKWARD, HORIZ_FORWARD(水平), HORIZ_BACKWARD(水平反向) d.scroll_to(下单, Direction.HORIZ_FORWARD, max_swipes5) # 也可以在指定元素内滚动 d.xpath(com.taobao.taobao:id/dx_root).scroll(Direction.HORIZ_FORWARD) d.xpath(com.taobao.taobao:id/dx_root).scroll_to(下单, Direction.HORIZ_FORWARD)源码实现XPathEntry.scroll_touiautomator2/xpath.py#L245-L275有三个要点方向换算FORWARD→UP、BACKWARD→DOWN、HORIZ_FORWARD→LEFT、HORIZ_BACKWARD→RIGHTswipe_ext语义是“从哪个方向滑起”每次未命中时以 0.5 的比例滑一屏命中后会先补一个 0.1 比例的小滑避免目标元素正好停在屏幕边缘难以点击max_swipes为滑动次数上限默认 10超出不返回元素。元素级XMLElement.scroll_touiautomator2/xpath.py#L634-L644则在每次滑动后检查scroll()的返回值一旦没有新元素出现就提前终止不会浪费剩余滑动次数。真机验证可参考 mobile_tests/test_xpath.py 的test_xpath_scroll_to在android:id/list内滚动直到找到 “Pictures”。一个综合示例以下完整脚本演示了点击、弹窗监控、遍历、滑动等组合用法摘自 XPATH.mdimport uiautomator2 as u2 from uiautomator2 import Direction def main(): d u2.connect() d.app_start(com.netease.cloudmusic, stopTrue) # steps d.xpath(//*[text私人FM]/../android.widget.ImageView).click() d.xpath(下一首).click() # 监控弹窗 2 秒实际时间可能大于 2 秒 d.xpath.sleep_watch(2) d.xpath(转到上一层级).click() d.xpath(转到上一层级).click(watchFalse) # 点击时不触发 watch d.xpath(转到上一层级).click(timeout5.0) # 等待超时 5 秒 d.xpath.watch_background() # 开启后台监控默认每 4 秒检查一次 d.xpath.watch_background(interval2.0) # 每 2 秒检查一次 d.xpath.watch_stop() # 停止监控 for el in d.xpath(//android.widget.EditText).all(): print(rect:, el.rect) # (left_x, top_y, width, height) print(bounds:, el.bounds) # (left, top, right, bottom) print(center:, el.center()) el.click() print(el.elem) # 滑动 el d.xpath(com.taobao.taobao:id/fl_banner_container).get() el.swipe(Direction.HORIZ_FORWARD) # 从右滑到左 el.swipe(Direction.LEFT) el.swipe(Direction.FORWARD) # 从下滑到上 el.swipe(Direction.UP) el.swipe(right, scale0.9) # 滑动距离为控件宽度的 90%起点中心对齐控件中心 el.swipe(up, scale0.5) # 滑动距离为控件高度的 50%注意sleep_watch/watch_background/watch_stop这几个d.xpath上的方法在源码中已标记 deprecateduiautomator2/xpath.py#L200-L228新代码建议直接使用 watcher 子系统d.watcher.when(跳过).when(知道了).click() # 级联条件 d.watcher.start(interval2.0) # 后台线程每 2 秒检查一次 d.watcher.stop()其中Watcher.start的默认 interval 为 2.0 秒uiautomator2/watcher.py#L168-L179触发过一次后下一次检查会缩短到 0.5 秒加快连续弹窗的处理节奏uiautomator2/watcher.py#L211-L218。watcher 的回调还支持自定义函数call(fn)可接收d、el参数和press(key)按键回调uiautomator2/watcher.py#L287-L323真机用例见 mobile_tests/test_xpath.py 的test_watcher。PageSource 对象3.1 新增PageSource是上述一切功能的地基几乎每个方法最终都会落到find_elements上。它从d.dump_hierarchy()的返回值初始化主要用法source d.xpath.get_page_source() # find_elements 是核心方法 elements source.find_elements(//android.widget.TextView) # List[XMLElement] for el in elements: print(el.text) # 获取坐标后点击 x, y elements[0].center() d.click(x, y) # 多种条件的查询写法 es1 source.find_elements(//android.widget.TextView) es2 source.find_elements(XPath(android:id/content).joinpath(//*)) # 找“是 TextView 但不属于 idandroid:id/content 下”的节点 els set(es1) - set(es2) # 找“是 TextView 且属于 idandroid:id/content 下”的节点 els set(es1) set(es2)集合运算之所以可行是因为XMLElement的重载了__hash__/__eq__基于 lxml 节点哈希uiautomator2/xpath.py#L539-L543。另外d.xpath(..., source...)允许传入已缓存的 XML 字符串作为查询源避免重复 dump——watcher 内部正是这么做的一次dump_hierarchy的结果被所有条件共享uiautomator2/watcher.py#L87-L105。XPath 的一些高级用法以下原生 XPath 表达式在 uiautomator2 中均可直接使用# 所有元素 //* # resource-id 包含 login 字符 //*[contains(resource-id, login)] # 按钮包含“账号”或“帐号” //android.widget.Button[contains(text, 账号) or contains(text, 帐号)] # 所有 ImageView 中的第二个 (//android.widget.ImageView)[2] # 所有 ImageView 中的最后一个 (//android.widget.ImageView)[last()] # className 包含 ImageView //*[contains(name(), ImageView)]特殊说明与字符转义有时className中含有$#等对 XML 不合法的字符这些字符会被统一替换成.。对应实现是safe_xmlstruiautomator2/xpath.py#L36-L40先把[$#]替换为.再合并连续点号、去掉首尾点号。单元测试 tests/test_xpath.py 验证了转换结果test$123 → test.123、$#123.456$ → 123.456。因此用//原生 XPath 按类名匹配时内部类名如com.foo.View$1要写成.形式。测试与验证XPath 扩展的行为有两条测试线可以佐证本文描述纯逻辑单测 tests/test_xpath.py用 mock 的 hierarchy XML 验证strict_xpath转换规则、XPath.joinpath、点击坐标计算命中[0,0][1080,100]时断言click(540, 50)、wait/wait_gone/exists/get的超时与异常行为、offset/screenshot/bounds等几何属性真机集成测试 mobile_tests/test_xpath.py覆盖%通配匹配、swipe后等待新元素、scroll_to列表内滚动查找、parent()条件定位、watcher 回调触发等场景。速查表需求写法按 resource-id 定位d.xpath(com.example:id/xxx)按文本模糊定位d.xpath(关键词)同时匹配 text/desc/id文本包含/前缀/后缀d.xpath(%词%)/d.xpath(词%)/d.xpath(%词)正则匹配d.xpath(^.*done)原生 XPathd.xpath(//android.widget.Button)条件 AND / OR(a b).get()/(a \| b).get()等出现 / 等消失sl.wait(timeout10)/sl.wait_gone(timeout10)存在即点sl.click_exists()找不到抛异常sl.get(timeout10)元素内滑动 / 滚动el.swipe(left, scale0.9)/el.scroll(Direction.FORWARD)列表内滚动查找d.xpath(...:id/list).scroll_to(目标, max_swipes10)弹窗自动处理d.watcher.when(继续安装).click(); d.watcher.start(interval2.0)中文版文档见 XPATH_CN.md实现细节集中在 uiautomator2/xpath.py可按本文给出的路径行号继续深入阅读。赞分享测试移动开发GUI 自动化【免费下载链接】uiautomator2Android Uiautomator2 Python Wrapper项目地址https://gitcode.com/gh_mirrors/ui/uiautomator2点击查看免费下载相关推荐Android Uiautomator2 Python Wrapper高级技巧XPath定位与元素操作全攻略Android Uiautomator2 Python Wrapper高级技巧XPath定位与元素操作全攻略 引言告别定位难题掌握自动化测试核心能力 你是测试移动开发GUI 自动化XPath Helper Plus网页元素定位的实战利器XPath Helper Plus网页元素定位的实战利器 如果你经常需要在网页中精准定位特定元素无论是为了自动化测试、数据抓取还是前端调试XPath He开发工具前端Android Uiautomator2 Python Wrapper元素等待机制解决90%的测试不稳定问题Android Uiautomator2 Python Wrapper元素等待机制解决90%的测试不稳定问题 引言自动化测试中的薛定谔元素现象 你是否遇测试移动开发GUI 自动化上一篇ExplorerPatcher 教程3 步把 Windows 11 改回 Win10 经典任务栏和开始菜单下一篇暗黑2存档编辑器教程4条命令本地跑起旧档读取一键满级创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考