1. 项目概述如果你是一名Android开发者或测试工程师过去几年里你肯定没少为自动化测试头疼。传统的Appium、Espresso框架写起来就像在解一道复杂的几何题你得先找到那个唯一的元素ID然后小心翼翼地编写脚本一旦UI改版整个测试脚本可能就废了。更别提那些动态加载的界面、不同分辨率的设备适配简直是测试工程师的噩梦。直到我遇到了UI-TARS这个基于视觉语言模型的开源智能体我才发现自动化测试原来可以如此“傻瓜式”操作。它不需要你懂复杂的元素定位也不需要你写冗长的脚本你只需要告诉它“打开应用输入账号密码然后点击登录”它就能像真人一样看着屏幕截图去理解和执行。最近UI-TARS在Android World benchmark上拿到了64.2的高分这让我决定花点时间把我从环境搭建到实战踩坑的完整经验整理成这篇终极指南。无论你是想提升测试效率的团队负责人还是刚入行的测试新手这篇文章都能帮你绕过我走过的弯路快速上手这个革命性的工具。2. UI-TARS核心架构与工作原理拆解在深入代码之前我们必须先搞清楚UI-TARS到底是怎么“想”和“做”的。它不是一个简单的脚本录制回放工具而是一个拥有“眼睛”和“大脑”的智能体。理解其三层架构是后续高效使用和问题排查的基础。2.1 环境层模拟真实用户的交互沙盒环境层是UI-TARS与Android设备交互的桥梁。它不直接操作物理设备或模拟器而是通过ADBAndroid Debug Bridge和屏幕截图流构建了一个虚拟的交互环境。你可以把它想象成一个游戏手柄UI-TARS是玩家而手机屏幕是游戏画面。这个环境层主要做三件事状态感知通过adb shell screencap命令以每秒数帧的频率捕获设备屏幕的实时图像。这是UI-TARS的“眼睛”。动作执行将高层指令如“点击(500, 800)”翻译成底层的ADB命令例如adb shell input tap 500 800。它支持点击、滑动、长按、文本输入、返回、Home键等所有基础交互。反馈循环执行一个动作后环境层会等待一个可配置的间隔通常是0.5-2秒然后再次截图将新的屏幕状态反馈给核心层形成一个“观察-思考-行动”的闭环。注意环境层的稳定性极度依赖ADB连接的稳定性。无线ADB虽然方便但在自动化测试中优先使用USB有线连接可以避免因网络波动导致的连接中断这是保证长流程测试稳定性的关键。2.2 核心模块层智能体的“大脑”这是UI-TARS最精华的部分它由多个协同工作的模块构成共同完成了从“看到”到“做到”的认知过程。感知模块当拿到一张屏幕截图后感知模块开始工作。它不仅仅做OCR文字识别更重要的是进行“元素描述”。例如对于一个蓝色的、圆形的、上面写着“登录”的按钮传统的工具需要你通过resource-id或xpath来定位它。而UI-TARS的感知模块会生成一个自然语言描述“屏幕底部中央有一个蓝色的圆形按钮上面有‘登录’文字”。这种基于视觉特征的描述使得它不惧UI改版——只要按钮看起来还是那个样子它就能认出来。推理模块这是智能的体现。当你下达一个复杂指令如“在购物应用中搜索‘无线耳机’并加入购物车”时推理模块会将这个长任务分解成一系列原子操作步骤1. 定位搜索框2. 输入文本3. 点击搜索按钮4. 浏览结果列表5. 识别并点击目标商品的“加入购物车”按钮。这个过程模仿了人类的系统化思考在内部被称为“System-2 Thinking”。动作模块它接收来自推理模块的原子指令如“点击‘登录’按钮”并将其转化为一个具体的、可执行的“动作轨迹”。这个轨迹不仅包括最终的点击坐标还可能包括为了到达那个坐标而进行的滑动路径例如需要先向上滑动屏幕才能看到按钮。它定义了一个统一的操作空间确保任何高层指令都能被映射为设备可执行的低层命令。学习模块持续进化这是UI-TARS区别于传统脚本工具的根本。它通过“轨迹自举”技术进行自我改进。简单说就是让AI自己尝试完成任务记录下成功的操作轨迹把这些轨迹作为新的训练数据反过来优化模型自己。此外还采用了Agent DPO直接偏好优化技术当模型在多个可行操作中做出选择时系统会引导它偏好更高效、更接近人类操作习惯的那一个让它的行为越来越“聪明”。2.3 用户交互层用自然语言对话这是最直观的一层。你不需要学习任何特定的脚本语法或领域特定语言DSL。你只需要用最直白的自然语言描述你的测试场景。例如“打开微信找到与张三的聊天窗口发送一句‘晚上一起吃饭’。” UI-TARS的交互层会理解你的意图并将其传递给核心模块。这一层通常通过Python API或未来可能提供的图形界面来体现。它降低了自动化测试的准入门槛让产品经理甚至业务人员都有可能直接描述测试用例这是对测试工作流的巨大革新。3. 从零开始环境搭建与快速验证理论讲完了我们动手把环境跑起来。这部分我会详细到每一个命令和可能遇到的坑确保你能一次成功。3.1 基础环境准备首先你需要一个Python环境建议3.8以上和一台Android设备真机或模拟器。步骤1安装UI-TARS包打开你的终端或命令提示符执行安装命令。这里有个小技巧使用清华镜像源可以大幅加快下载速度。pip install ui-tars -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后强烈建议你顺手安装pillow库后续我们处理截图和可视化时会用到。pip install pillow步骤2配置Android调试环境这是整个流程中最容易出问题的一环请仔细核对。启用开发者选项在手机的“设置”-“关于手机”中连续点击“版本号”7次。开启USB调试进入新出现的“开发者选项”找到“USB调试”打开它。连接电脑用USB数据线连接手机和电脑。在手机弹出的“允许USB调试吗”对话框中选择“允许”并勾选“始终允许”。验证连接在电脑终端输入adb devices你应该能看到类似List of devices attached和一行设备序列号后面跟着device字样。如果显示unauthorized请重新插拔数据线并在手机上确认授权。实操心得对于模拟器如Android Studio自带的AVDADB连接通常是自动建立的。如果adb devices找不到模拟器可以尝试重启ADB服务adb kill-server然后adb start-server。步骤3获取设备关键信息我们需要知道屏幕分辨率用于后续的坐标转换。执行adb shell wm size输出通常是Physical size: 1080x2340。记下这两个数字宽和高。同时获取屏幕密度adb shell wm density这些信息在编写跨设备兼容的测试脚本时非常重要。3.2 你的第一个“Hello World”测试我们来写一个最简单的脚本验证整个链路是否通畅让UI-TARS帮我们打开手机的设置菜单。import ui_tars import time from ui_tars.prompt import get_prompt_template # 1. 定义你的测试任务用最自然的语言 task_description 请打开手机的系统设置应用。 # 2. 选择移动设备专用的指令模板 prompt_template get_prompt_template(MOBILE_USE) # 将你的任务描述填充到模板中 prompt prompt_template.format(instructiontask_description) print(生成的指令提示) print(prompt) print(\n--- 请注意以下需要接入大模型API ---\n) # 3. 模拟调用视觉语言模型 # 此处需要你自行接入如Qwen-VL、GPT-4V等模型的API # 假设 call_vlm_api 是你封装好的函数传入截图和prompt返回模型的文本响应 # screenshot adb_screencap() # 你需要实现截图函数 # model_response call_vlm_api(screenshot, prompt) # 4. 解析模型的响应将其转化为结构化的动作 # 假设我们已经得到了一个模拟的模型响应 simulated_response 我需要打开设置。首先我需要回到主屏幕确保在初始状态。按下Home键。然后在主屏幕上找到“设置”应用图标它通常是一个齿轮状的图标。点击它。 from ui_tars.action_parser import parse_action_to_structure_output # 解析响应factor1000意味着坐标是相对于1000x1000标准空间的后续会缩放 parsed_actions parse_action_to_structure_output( responsesimulated_response, factor1000, origin_resized_height2340, # 替换为你的设备高度 origin_resized_width1080, # 替换为你的设备宽度 model_typeqwen25vl # 根据你使用的模型类型指定 ) print(解析出的动作序列) for i, action in enumerate(parsed_actions): print(f{i1}. {action}) # 5. 将结构化动作转换为可执行的PyAutoGUI代码或直接执行 from ui_tars.action_parser import parsing_response_to_pyautogui_code automation_script parsing_response_to_pyautogui_code( responsesparsed_actions, image_height2340, image_width1080 ) # 将生成的脚本保存到文件 with open(open_settings.py, w) as f: f.write(automation_script) print(\n自动化脚本已生成到 open_settings.py) print(你可以使用 python open_settings.py 来运行它需安装pyautogui。)这个脚本展示了UI-TARS标准的工作流描述任务 - 模型思考 - 解析动作 - 生成代码。目前你需要自己对接第3步的视觉模型API。社区正在努力提供更一体化的解决方案。4. 核心功能实战构建一个完整的自动化测试用例现在我们用一个更贴近实际业务的例子来深入自动化测试一个简易登录应用。假设我们有一个APP有用户名输入框、密码输入框和登录按钮。4.1 定义清晰的测试任务任务描述的清晰度直接决定了模型的成功率。避免模糊指令。task_description 你现在要测试一个登录应用。请完成以下操作 1. 在手机主屏幕找到名为“LoginDemo”的应用图标并打开它。 2. 应用打开后你会看到界面。顶部有一个文本框提示文字是“Username”请点击这个文本框并输入文字“test_user”。 3. 输入完成后找到在Username文本框下方的一个文本框提示文字是“Password”点击它并输入“password123”。 4. 找到屏幕上的一个蓝色长方形按钮上面的文字是“LOG IN”点击这个按钮。 5. 点击后如果登录成功界面通常会跳转或出现“Welcome”之类的文字。请等待3秒观察界面变化。 为什么这样写“找到名为...的应用图标”指明了启动路径。“提示文字是...”提供了精准的视觉/文本定位线索这比说“第一个输入框”更可靠。“蓝色长方形按钮”结合颜色、形状和文字“LOG IN”进行多重定位容错率更高。“等待3秒观察”给网络请求和界面跳转留出时间是稳定性的关键。4.2 处理坐标与设备适配UI-TARS模型通常在一个标准分辨率如1000x1000的归一化空间中输出坐标。parse_action_to_structure_output函数中的origin_resized_height和origin_resized_width参数就是用来将这些归一化坐标映射回你真实设备坐标的。坐标转换原理 假设模型说点击位置是 (500, 300)在1000x1000空间内。 你的真实设备分辨率是 1080x2340。 那么转换后的真实坐标是real_x 500 / 1000 * 1080 540 real_y 300 / 1000 * 2340 702action_parser模块内部帮你完成了这个数学计算。这就是为什么你必须准确传入设备分辨率。常见问题如果测试脚本在真机上点击位置总是有偏移可能是屏幕有圆角、刘海屏或状态栏占用了空间。解决方案是在获取wm size的基础上尝试获取可用的显示区域adb shell wm size | grep -oP ‘Override size: \K.*‘如果存在或者在脚本中引入一个全局的坐标偏移量进行校准。4.3 生成与执行自动化脚本解析出动作后我们可以生成PyAutoGUI脚本。PyAutoGUI是一个跨平台的GUI自动化库但它本身不能直接控制手机。因此生成的脚本通常需要配合adb shell input命令来执行。from ui_tars.action_parser import parsing_response_to_pyautogui_code import subprocess import time # 生成PyAutoGUI格式的代码 code parsing_response_to_pyautogui_code( responsesparsed_actions, # 上一步解析出的动作列表 image_height2340, image_width1080 ) # 生成的代码片段可能包含 pyautogui.click(x, y) # 但我们需要将其转换为ADB命令 def pyautogui_click_to_adb(x, y): 将PyAutoGUI点击坐标转换为ADB点击命令 # 这里可能需要进行额外的坐标校准 calibrated_x, calibrated_y calibrate_coordinates(x, y) command fadb shell input tap {calibrated_x} {calibrated_y} return command # 一个简单的校准函数示例你需要根据自己设备调整 def calibrate_coordinates(x, y): # 例如如果你的设备状态栏高100像素所有y坐标需要100 offset_y 100 return int(x), int(y offset_y) # 模拟执行生成的代码中的点击操作 for line in code.split(\n): if pyautogui.click in line: # 简陋地提取坐标实际应用应用更稳健的方法如正则表达式 # 例如: pyautogui.click(540, 702) import re match re.search(r\((\d),\s*(\d)\), line) if match: x, y int(match.group(1)), int(match.group(2)) adb_command pyautogui_click_to_adb(x, y) print(f执行: {adb_command}) # 实际执行ADB命令 # subprocess.run(adb_command, shellTrue) time.sleep(1) # 在操作之间加入延迟模拟真人操作间隔这段代码展示了从UI-TARS生成代码到最终在设备上执行的关键转换步骤。在实际项目中你可能需要封装一个更强大的“执行器”来解析各种PyAutoGUI命令click, typewrite, press等并映射到对应的ADB命令。5. 高级技巧与稳定性优化直接跑通基础流程只是开始要想把UI-TARS用于严肃的测试任务必须考虑稳定性和健壮性。下面是我在实战中总结的几个关键技巧。5.1 实现智能等待与重试机制模型识别和网络请求都有不确定性固定的time.sleep不是最佳选择。应该实现基于状态的等待。import time from PIL import Image import io import subprocess def wait_for_screen_stable(device_id, timeout10, check_interval1): 等待屏幕内容稳定例如加载动画停止。 通过比较连续截图的差异来判断。 prev_image None start_time time.time() while time.time() - start_time timeout: # 获取当前截图 current_image take_screenshot(device_id) if prev_image is not None: # 计算两张图片的差异度这里使用简单的像素差异可改用更高级的SSIM diff image_difference(prev_image, current_image) if diff 5: # 差异小于5%认为已稳定 print(屏幕已稳定。) return True prev_image current_image time.sleep(check_interval) print(f等待屏幕稳定超时{timeout}秒。) return False def retry_operation(operation_func, max_retries3, delay2): 对某个操作进行重试的装饰器/函数 for attempt in range(max_retries): try: result operation_func() print(f操作在第 {attempt1} 次尝试成功。) return result except Exception as e: print(f第 {attempt1} 次尝试失败: {e}) if attempt max_retries - 1: print(f{delay}秒后重试...) time.sleep(delay) else: print(已达到最大重试次数操作失败。) raise在你的测试流程中关键步骤前后插入wait_for_screen_stable()并用retry_operation包裹可能失败的操作如点击一个可能尚未加载出来的按钮。5.2 动态元素与模糊匹配策略有时UI元素文本会动态变化如“剩余3秒”或者模型无法精确识别。我们需要更灵活的匹配策略。策略一特征组合匹配在任务描述中不要只依赖文字。结合颜色、形状、相对位置。劣质描述“点击确定按钮。”优质描述“点击屏幕底部那个蓝色的、圆角矩形的‘确定’按钮。”策略二使用相对坐标或区域如果某个按钮始终在屏幕固定区域可以指导模型使用相对坐标。示例“在屏幕中央偏右的区域屏幕宽度70%-90%高度50%-70%的范围内找到并点击那个红色的开关。”策略三后处理校验在执行一个关键操作如点击登录后通过OCR快速检查屏幕是否出现了预期的结果文字如“登录成功”或“Welcome”以此作为该步骤是否成功的判断而不是单纯依赖是否点击了。5.3 测试用例的数据驱动与参数化真正的自动化测试需要数据驱动。我们可以将UI-TARS的任务描述模板化。def generate_login_task(username, password, app_nameLoginDemo): 生成参数化的登录任务描述 task_template 测试登录功能。 1. 打开名为“{app}”的应用。 2. 在用户名输入框提示文字为“Username”或“邮箱”中输入“{user}”。 3. 在密码输入框提示文字为“Password”或“密码”中输入“{pwd}”。 4. 点击“登录”或“LOG IN”按钮。 5. 等待并检查是否出现登录成功的提示。 return task_template.format(appapp_name, userusername, pwdpassword) # 从CSV或JSON文件读取测试数据 test_data [ {user: admin, pwd: admin123, expected: success}, {user: test, pwd: wrong, expected: fail}, {user: , pwd: password, expected: fail}, # 空用户名 ] for data in test_data: print(f\n 执行测试用例: 用户名{data[user]} ) task generate_login_task(data[user], data[pwd]) # 将task送入UI-TARS流程... # ... 执行自动化 ... # 验证结果是否与data[expected]匹配这样你只需要维护一份测试数据文件就能自动生成和执行大量测试用例。6. 常见问题排查与实战心得即使准备得再充分实际运行中还是会遇到各种问题。这里我列出了一个速查表涵盖了最常见的情况和我的解决方案。问题现象可能原因排查步骤与解决方案adb devices列表为空1. USB线或端口故障2. 手机未授权3. ADB服务未启动1. 换线、换端口。2. 重新插拔确认手机弹窗并点击“允许”。3. 运行adb kill-server adb start-server。模型识别错误点击了错误位置1. 任务描述模糊2. 截图质量差/有动态内容3. 坐标转换错误1.优化描述增加元素特征颜色、形状、相邻文字。2.确保截图稳定在操作前加入等待避开加载动画。3.校准坐标编写一个校准脚本让UI-TARS点击屏幕已知位置如四个角记录偏差并修正。脚本运行速度过快导致应用崩溃操作间隔太短应用来不及响应在关键操作间添加智能等待使用wait_for_screen_stable函数而非固定time.sleep。对于网络请求等待时间可适当延长至3-5秒。在某个界面卡住重复执行无效操作模型陷入了“死循环”或状态判断错误引入超时与状态检查为每个主要步骤设置超时如30秒。在循环操作前检查屏幕是否已处于目标状态例如通过OCR检查是否已出现“登录成功”字样。生成的PyAutoGUI代码无法在手机上运行PyAutoGUI用于桌面不能直接控制手机使用ADB命令执行器如前文所述需要将pyautogui.click(x, y)转换为adb shell input tap x y。你需要自己编写或寻找一个“移动端执行器”适配层。在不同分辨率设备上运行不一致坐标转换未正确适配目标设备动态获取分辨率在脚本开始时通过adb shell wm size动态获取当前设备分辨率并以此参数调用parse_action_to_structure_output和parsing_response_to_pyautogui_code。处理弹窗或权限请求意外弹窗打断了流程增加弹窗处理逻辑在主要任务流中周期性检查屏幕是否有常见弹窗元素如“允许”、“拒绝”、“确定”并制定处理策略通常点击“允许”或“确定”。可以将此作为“巡检”任务插入到各个步骤之间。我个人最深刻的实战心得有两点 第一任务描述是指令更是契约。你描述得越像在教一个眼神不太好但很听话的新人UI-TARS就执行得越好。避免使用“这里”、“那里”等指代不清的词。 第二不要追求100%的全无人值守。尤其是初期将UI-TARS定位为一个“超级测试助手”让它处理重复、固定的流程而由人来监督和处置异常。随着你不断优化描述、增加重试和校验逻辑它的自主性会越来越强。先实现80%场景的自动化剩下的20%复杂异常场景其ROI投资回报率可能不高需酌情考虑。UI-TARS代表的是一种范式转移从“基于元素定位的脚本测试”转向“基于视觉理解的智能交互”。它目前可能还不是解决所有测试问题的银弹在极端复杂和动态的UI面前仍会挑战但它无疑大幅降低了自动化测试的启动门槛和维护成本。我的建议是从一个小而具体的测试场景开始比如某个核心功能的冒烟测试逐步积累经验和信心你会发现团队能更快地获得质量反馈从而更早、更频繁地发现问题。
UI-TARS：基于视觉语言模型的Android自动化测试实战指南
1. 项目概述如果你是一名Android开发者或测试工程师过去几年里你肯定没少为自动化测试头疼。传统的Appium、Espresso框架写起来就像在解一道复杂的几何题你得先找到那个唯一的元素ID然后小心翼翼地编写脚本一旦UI改版整个测试脚本可能就废了。更别提那些动态加载的界面、不同分辨率的设备适配简直是测试工程师的噩梦。直到我遇到了UI-TARS这个基于视觉语言模型的开源智能体我才发现自动化测试原来可以如此“傻瓜式”操作。它不需要你懂复杂的元素定位也不需要你写冗长的脚本你只需要告诉它“打开应用输入账号密码然后点击登录”它就能像真人一样看着屏幕截图去理解和执行。最近UI-TARS在Android World benchmark上拿到了64.2的高分这让我决定花点时间把我从环境搭建到实战踩坑的完整经验整理成这篇终极指南。无论你是想提升测试效率的团队负责人还是刚入行的测试新手这篇文章都能帮你绕过我走过的弯路快速上手这个革命性的工具。2. UI-TARS核心架构与工作原理拆解在深入代码之前我们必须先搞清楚UI-TARS到底是怎么“想”和“做”的。它不是一个简单的脚本录制回放工具而是一个拥有“眼睛”和“大脑”的智能体。理解其三层架构是后续高效使用和问题排查的基础。2.1 环境层模拟真实用户的交互沙盒环境层是UI-TARS与Android设备交互的桥梁。它不直接操作物理设备或模拟器而是通过ADBAndroid Debug Bridge和屏幕截图流构建了一个虚拟的交互环境。你可以把它想象成一个游戏手柄UI-TARS是玩家而手机屏幕是游戏画面。这个环境层主要做三件事状态感知通过adb shell screencap命令以每秒数帧的频率捕获设备屏幕的实时图像。这是UI-TARS的“眼睛”。动作执行将高层指令如“点击(500, 800)”翻译成底层的ADB命令例如adb shell input tap 500 800。它支持点击、滑动、长按、文本输入、返回、Home键等所有基础交互。反馈循环执行一个动作后环境层会等待一个可配置的间隔通常是0.5-2秒然后再次截图将新的屏幕状态反馈给核心层形成一个“观察-思考-行动”的闭环。注意环境层的稳定性极度依赖ADB连接的稳定性。无线ADB虽然方便但在自动化测试中优先使用USB有线连接可以避免因网络波动导致的连接中断这是保证长流程测试稳定性的关键。2.2 核心模块层智能体的“大脑”这是UI-TARS最精华的部分它由多个协同工作的模块构成共同完成了从“看到”到“做到”的认知过程。感知模块当拿到一张屏幕截图后感知模块开始工作。它不仅仅做OCR文字识别更重要的是进行“元素描述”。例如对于一个蓝色的、圆形的、上面写着“登录”的按钮传统的工具需要你通过resource-id或xpath来定位它。而UI-TARS的感知模块会生成一个自然语言描述“屏幕底部中央有一个蓝色的圆形按钮上面有‘登录’文字”。这种基于视觉特征的描述使得它不惧UI改版——只要按钮看起来还是那个样子它就能认出来。推理模块这是智能的体现。当你下达一个复杂指令如“在购物应用中搜索‘无线耳机’并加入购物车”时推理模块会将这个长任务分解成一系列原子操作步骤1. 定位搜索框2. 输入文本3. 点击搜索按钮4. 浏览结果列表5. 识别并点击目标商品的“加入购物车”按钮。这个过程模仿了人类的系统化思考在内部被称为“System-2 Thinking”。动作模块它接收来自推理模块的原子指令如“点击‘登录’按钮”并将其转化为一个具体的、可执行的“动作轨迹”。这个轨迹不仅包括最终的点击坐标还可能包括为了到达那个坐标而进行的滑动路径例如需要先向上滑动屏幕才能看到按钮。它定义了一个统一的操作空间确保任何高层指令都能被映射为设备可执行的低层命令。学习模块持续进化这是UI-TARS区别于传统脚本工具的根本。它通过“轨迹自举”技术进行自我改进。简单说就是让AI自己尝试完成任务记录下成功的操作轨迹把这些轨迹作为新的训练数据反过来优化模型自己。此外还采用了Agent DPO直接偏好优化技术当模型在多个可行操作中做出选择时系统会引导它偏好更高效、更接近人类操作习惯的那一个让它的行为越来越“聪明”。2.3 用户交互层用自然语言对话这是最直观的一层。你不需要学习任何特定的脚本语法或领域特定语言DSL。你只需要用最直白的自然语言描述你的测试场景。例如“打开微信找到与张三的聊天窗口发送一句‘晚上一起吃饭’。” UI-TARS的交互层会理解你的意图并将其传递给核心模块。这一层通常通过Python API或未来可能提供的图形界面来体现。它降低了自动化测试的准入门槛让产品经理甚至业务人员都有可能直接描述测试用例这是对测试工作流的巨大革新。3. 从零开始环境搭建与快速验证理论讲完了我们动手把环境跑起来。这部分我会详细到每一个命令和可能遇到的坑确保你能一次成功。3.1 基础环境准备首先你需要一个Python环境建议3.8以上和一台Android设备真机或模拟器。步骤1安装UI-TARS包打开你的终端或命令提示符执行安装命令。这里有个小技巧使用清华镜像源可以大幅加快下载速度。pip install ui-tars -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后强烈建议你顺手安装pillow库后续我们处理截图和可视化时会用到。pip install pillow步骤2配置Android调试环境这是整个流程中最容易出问题的一环请仔细核对。启用开发者选项在手机的“设置”-“关于手机”中连续点击“版本号”7次。开启USB调试进入新出现的“开发者选项”找到“USB调试”打开它。连接电脑用USB数据线连接手机和电脑。在手机弹出的“允许USB调试吗”对话框中选择“允许”并勾选“始终允许”。验证连接在电脑终端输入adb devices你应该能看到类似List of devices attached和一行设备序列号后面跟着device字样。如果显示unauthorized请重新插拔数据线并在手机上确认授权。实操心得对于模拟器如Android Studio自带的AVDADB连接通常是自动建立的。如果adb devices找不到模拟器可以尝试重启ADB服务adb kill-server然后adb start-server。步骤3获取设备关键信息我们需要知道屏幕分辨率用于后续的坐标转换。执行adb shell wm size输出通常是Physical size: 1080x2340。记下这两个数字宽和高。同时获取屏幕密度adb shell wm density这些信息在编写跨设备兼容的测试脚本时非常重要。3.2 你的第一个“Hello World”测试我们来写一个最简单的脚本验证整个链路是否通畅让UI-TARS帮我们打开手机的设置菜单。import ui_tars import time from ui_tars.prompt import get_prompt_template # 1. 定义你的测试任务用最自然的语言 task_description 请打开手机的系统设置应用。 # 2. 选择移动设备专用的指令模板 prompt_template get_prompt_template(MOBILE_USE) # 将你的任务描述填充到模板中 prompt prompt_template.format(instructiontask_description) print(生成的指令提示) print(prompt) print(\n--- 请注意以下需要接入大模型API ---\n) # 3. 模拟调用视觉语言模型 # 此处需要你自行接入如Qwen-VL、GPT-4V等模型的API # 假设 call_vlm_api 是你封装好的函数传入截图和prompt返回模型的文本响应 # screenshot adb_screencap() # 你需要实现截图函数 # model_response call_vlm_api(screenshot, prompt) # 4. 解析模型的响应将其转化为结构化的动作 # 假设我们已经得到了一个模拟的模型响应 simulated_response 我需要打开设置。首先我需要回到主屏幕确保在初始状态。按下Home键。然后在主屏幕上找到“设置”应用图标它通常是一个齿轮状的图标。点击它。 from ui_tars.action_parser import parse_action_to_structure_output # 解析响应factor1000意味着坐标是相对于1000x1000标准空间的后续会缩放 parsed_actions parse_action_to_structure_output( responsesimulated_response, factor1000, origin_resized_height2340, # 替换为你的设备高度 origin_resized_width1080, # 替换为你的设备宽度 model_typeqwen25vl # 根据你使用的模型类型指定 ) print(解析出的动作序列) for i, action in enumerate(parsed_actions): print(f{i1}. {action}) # 5. 将结构化动作转换为可执行的PyAutoGUI代码或直接执行 from ui_tars.action_parser import parsing_response_to_pyautogui_code automation_script parsing_response_to_pyautogui_code( responsesparsed_actions, image_height2340, image_width1080 ) # 将生成的脚本保存到文件 with open(open_settings.py, w) as f: f.write(automation_script) print(\n自动化脚本已生成到 open_settings.py) print(你可以使用 python open_settings.py 来运行它需安装pyautogui。)这个脚本展示了UI-TARS标准的工作流描述任务 - 模型思考 - 解析动作 - 生成代码。目前你需要自己对接第3步的视觉模型API。社区正在努力提供更一体化的解决方案。4. 核心功能实战构建一个完整的自动化测试用例现在我们用一个更贴近实际业务的例子来深入自动化测试一个简易登录应用。假设我们有一个APP有用户名输入框、密码输入框和登录按钮。4.1 定义清晰的测试任务任务描述的清晰度直接决定了模型的成功率。避免模糊指令。task_description 你现在要测试一个登录应用。请完成以下操作 1. 在手机主屏幕找到名为“LoginDemo”的应用图标并打开它。 2. 应用打开后你会看到界面。顶部有一个文本框提示文字是“Username”请点击这个文本框并输入文字“test_user”。 3. 输入完成后找到在Username文本框下方的一个文本框提示文字是“Password”点击它并输入“password123”。 4. 找到屏幕上的一个蓝色长方形按钮上面的文字是“LOG IN”点击这个按钮。 5. 点击后如果登录成功界面通常会跳转或出现“Welcome”之类的文字。请等待3秒观察界面变化。 为什么这样写“找到名为...的应用图标”指明了启动路径。“提示文字是...”提供了精准的视觉/文本定位线索这比说“第一个输入框”更可靠。“蓝色长方形按钮”结合颜色、形状和文字“LOG IN”进行多重定位容错率更高。“等待3秒观察”给网络请求和界面跳转留出时间是稳定性的关键。4.2 处理坐标与设备适配UI-TARS模型通常在一个标准分辨率如1000x1000的归一化空间中输出坐标。parse_action_to_structure_output函数中的origin_resized_height和origin_resized_width参数就是用来将这些归一化坐标映射回你真实设备坐标的。坐标转换原理 假设模型说点击位置是 (500, 300)在1000x1000空间内。 你的真实设备分辨率是 1080x2340。 那么转换后的真实坐标是real_x 500 / 1000 * 1080 540 real_y 300 / 1000 * 2340 702action_parser模块内部帮你完成了这个数学计算。这就是为什么你必须准确传入设备分辨率。常见问题如果测试脚本在真机上点击位置总是有偏移可能是屏幕有圆角、刘海屏或状态栏占用了空间。解决方案是在获取wm size的基础上尝试获取可用的显示区域adb shell wm size | grep -oP ‘Override size: \K.*‘如果存在或者在脚本中引入一个全局的坐标偏移量进行校准。4.3 生成与执行自动化脚本解析出动作后我们可以生成PyAutoGUI脚本。PyAutoGUI是一个跨平台的GUI自动化库但它本身不能直接控制手机。因此生成的脚本通常需要配合adb shell input命令来执行。from ui_tars.action_parser import parsing_response_to_pyautogui_code import subprocess import time # 生成PyAutoGUI格式的代码 code parsing_response_to_pyautogui_code( responsesparsed_actions, # 上一步解析出的动作列表 image_height2340, image_width1080 ) # 生成的代码片段可能包含 pyautogui.click(x, y) # 但我们需要将其转换为ADB命令 def pyautogui_click_to_adb(x, y): 将PyAutoGUI点击坐标转换为ADB点击命令 # 这里可能需要进行额外的坐标校准 calibrated_x, calibrated_y calibrate_coordinates(x, y) command fadb shell input tap {calibrated_x} {calibrated_y} return command # 一个简单的校准函数示例你需要根据自己设备调整 def calibrate_coordinates(x, y): # 例如如果你的设备状态栏高100像素所有y坐标需要100 offset_y 100 return int(x), int(y offset_y) # 模拟执行生成的代码中的点击操作 for line in code.split(\n): if pyautogui.click in line: # 简陋地提取坐标实际应用应用更稳健的方法如正则表达式 # 例如: pyautogui.click(540, 702) import re match re.search(r\((\d),\s*(\d)\), line) if match: x, y int(match.group(1)), int(match.group(2)) adb_command pyautogui_click_to_adb(x, y) print(f执行: {adb_command}) # 实际执行ADB命令 # subprocess.run(adb_command, shellTrue) time.sleep(1) # 在操作之间加入延迟模拟真人操作间隔这段代码展示了从UI-TARS生成代码到最终在设备上执行的关键转换步骤。在实际项目中你可能需要封装一个更强大的“执行器”来解析各种PyAutoGUI命令click, typewrite, press等并映射到对应的ADB命令。5. 高级技巧与稳定性优化直接跑通基础流程只是开始要想把UI-TARS用于严肃的测试任务必须考虑稳定性和健壮性。下面是我在实战中总结的几个关键技巧。5.1 实现智能等待与重试机制模型识别和网络请求都有不确定性固定的time.sleep不是最佳选择。应该实现基于状态的等待。import time from PIL import Image import io import subprocess def wait_for_screen_stable(device_id, timeout10, check_interval1): 等待屏幕内容稳定例如加载动画停止。 通过比较连续截图的差异来判断。 prev_image None start_time time.time() while time.time() - start_time timeout: # 获取当前截图 current_image take_screenshot(device_id) if prev_image is not None: # 计算两张图片的差异度这里使用简单的像素差异可改用更高级的SSIM diff image_difference(prev_image, current_image) if diff 5: # 差异小于5%认为已稳定 print(屏幕已稳定。) return True prev_image current_image time.sleep(check_interval) print(f等待屏幕稳定超时{timeout}秒。) return False def retry_operation(operation_func, max_retries3, delay2): 对某个操作进行重试的装饰器/函数 for attempt in range(max_retries): try: result operation_func() print(f操作在第 {attempt1} 次尝试成功。) return result except Exception as e: print(f第 {attempt1} 次尝试失败: {e}) if attempt max_retries - 1: print(f{delay}秒后重试...) time.sleep(delay) else: print(已达到最大重试次数操作失败。) raise在你的测试流程中关键步骤前后插入wait_for_screen_stable()并用retry_operation包裹可能失败的操作如点击一个可能尚未加载出来的按钮。5.2 动态元素与模糊匹配策略有时UI元素文本会动态变化如“剩余3秒”或者模型无法精确识别。我们需要更灵活的匹配策略。策略一特征组合匹配在任务描述中不要只依赖文字。结合颜色、形状、相对位置。劣质描述“点击确定按钮。”优质描述“点击屏幕底部那个蓝色的、圆角矩形的‘确定’按钮。”策略二使用相对坐标或区域如果某个按钮始终在屏幕固定区域可以指导模型使用相对坐标。示例“在屏幕中央偏右的区域屏幕宽度70%-90%高度50%-70%的范围内找到并点击那个红色的开关。”策略三后处理校验在执行一个关键操作如点击登录后通过OCR快速检查屏幕是否出现了预期的结果文字如“登录成功”或“Welcome”以此作为该步骤是否成功的判断而不是单纯依赖是否点击了。5.3 测试用例的数据驱动与参数化真正的自动化测试需要数据驱动。我们可以将UI-TARS的任务描述模板化。def generate_login_task(username, password, app_nameLoginDemo): 生成参数化的登录任务描述 task_template 测试登录功能。 1. 打开名为“{app}”的应用。 2. 在用户名输入框提示文字为“Username”或“邮箱”中输入“{user}”。 3. 在密码输入框提示文字为“Password”或“密码”中输入“{pwd}”。 4. 点击“登录”或“LOG IN”按钮。 5. 等待并检查是否出现登录成功的提示。 return task_template.format(appapp_name, userusername, pwdpassword) # 从CSV或JSON文件读取测试数据 test_data [ {user: admin, pwd: admin123, expected: success}, {user: test, pwd: wrong, expected: fail}, {user: , pwd: password, expected: fail}, # 空用户名 ] for data in test_data: print(f\n 执行测试用例: 用户名{data[user]} ) task generate_login_task(data[user], data[pwd]) # 将task送入UI-TARS流程... # ... 执行自动化 ... # 验证结果是否与data[expected]匹配这样你只需要维护一份测试数据文件就能自动生成和执行大量测试用例。6. 常见问题排查与实战心得即使准备得再充分实际运行中还是会遇到各种问题。这里我列出了一个速查表涵盖了最常见的情况和我的解决方案。问题现象可能原因排查步骤与解决方案adb devices列表为空1. USB线或端口故障2. 手机未授权3. ADB服务未启动1. 换线、换端口。2. 重新插拔确认手机弹窗并点击“允许”。3. 运行adb kill-server adb start-server。模型识别错误点击了错误位置1. 任务描述模糊2. 截图质量差/有动态内容3. 坐标转换错误1.优化描述增加元素特征颜色、形状、相邻文字。2.确保截图稳定在操作前加入等待避开加载动画。3.校准坐标编写一个校准脚本让UI-TARS点击屏幕已知位置如四个角记录偏差并修正。脚本运行速度过快导致应用崩溃操作间隔太短应用来不及响应在关键操作间添加智能等待使用wait_for_screen_stable函数而非固定time.sleep。对于网络请求等待时间可适当延长至3-5秒。在某个界面卡住重复执行无效操作模型陷入了“死循环”或状态判断错误引入超时与状态检查为每个主要步骤设置超时如30秒。在循环操作前检查屏幕是否已处于目标状态例如通过OCR检查是否已出现“登录成功”字样。生成的PyAutoGUI代码无法在手机上运行PyAutoGUI用于桌面不能直接控制手机使用ADB命令执行器如前文所述需要将pyautogui.click(x, y)转换为adb shell input tap x y。你需要自己编写或寻找一个“移动端执行器”适配层。在不同分辨率设备上运行不一致坐标转换未正确适配目标设备动态获取分辨率在脚本开始时通过adb shell wm size动态获取当前设备分辨率并以此参数调用parse_action_to_structure_output和parsing_response_to_pyautogui_code。处理弹窗或权限请求意外弹窗打断了流程增加弹窗处理逻辑在主要任务流中周期性检查屏幕是否有常见弹窗元素如“允许”、“拒绝”、“确定”并制定处理策略通常点击“允许”或“确定”。可以将此作为“巡检”任务插入到各个步骤之间。我个人最深刻的实战心得有两点 第一任务描述是指令更是契约。你描述得越像在教一个眼神不太好但很听话的新人UI-TARS就执行得越好。避免使用“这里”、“那里”等指代不清的词。 第二不要追求100%的全无人值守。尤其是初期将UI-TARS定位为一个“超级测试助手”让它处理重复、固定的流程而由人来监督和处置异常。随着你不断优化描述、增加重试和校验逻辑它的自主性会越来越强。先实现80%场景的自动化剩下的20%复杂异常场景其ROI投资回报率可能不高需酌情考虑。UI-TARS代表的是一种范式转移从“基于元素定位的脚本测试”转向“基于视觉理解的智能交互”。它目前可能还不是解决所有测试问题的银弹在极端复杂和动态的UI面前仍会挑战但它无疑大幅降低了自动化测试的启动门槛和维护成本。我的建议是从一个小而具体的测试场景开始比如某个核心功能的冒烟测试逐步积累经验和信心你会发现团队能更快地获得质量反馈从而更早、更频繁地发现问题。
