做移动端测试这些年前前后后搭过不下五套 UI 自动化的方案最后留在项目里长期跑的还是 Appium 移动端 UI 自动化测试框架。简单说它就是一套让脚本模拟手指点击、滑动、输入、断言的测试工具覆盖 Android 和 iOS官方和社区还维护了 Python、Java、JavaScript 等多种语言的客户端库同一套能力可以跨平台复用。这篇指南我会把从零搭建整套框架的流程讲透包括环境准备、架构原理、代码分层、问题排查和稳定性经验全程只讲实测可复现的做法适合刚开始接触移动端自动化、准备在团队里正式落地框架的测试工程师也适合已经写过几个脚本、但想把它工程化和规范化的同学。先给个忠告框架这件事想清楚再动手比急着敲命令重要得多。1. 为什么选 Appium先回答三个问题1.1 它到底解决了什么问题移动端回归测试有个老大难版本迭代快、兼容矩阵多、手工回归费人。Appium 解决的正是用机器替代人重复劳动的问题——冒烟测试、核心链路回归、多机型兼容性验证都能交给脚本在夜间执行第二天早上直接看报告。它有四个特性是当初我们在某项目组选型时最看重的跨平台同一套 API 操作 Android 和 iOS底层驱动自动切换不用为每个平台单独写一套跨语言Python、Java、Ruby、JavaScript 都有官方客户端团队熟悉什么语言就用什么不需要全员转语言黑盒驱动不依赖被测应用的源码只要 App 能装、能跑就能测对研发团队来说接入成本低生态成熟社区资料量很大踩过的坑基本都能搜到现成方案这一点在技术选型里非常重要。我见过不少团队一上来就追求大而全结果用例跑两天就垮。所以这里先明确Appium 不是银弹。它适合产品形态相对稳定、有持续迭代节奏、且团队愿意长期维护测试代码的场景。反过来如果项目面向核心功能频繁改版或者团队连一个专职自动化的人都没有那建议先不要上手工探索性测试加上简单的脚本巡检反而划算。1.2 和同类方案对比后为什么仍选它选型阶段我们对比过几个方向平台官方推荐的原生驱动方案、录制回放类工具以及各类云真机平台。这里放一张基于我们实际使用感受的对比表方案跨平台执行速度维护成本适用场景Appium好中等中高跨平台回归、端到端流程验证平台原生驱动差按平台分开快中等单平台深度专项、性能验证录制回放工具一般快高临时冒烟不适合规模化沉淀云真机平台好中等低按量付费多机型覆盖、线下设备不足结论就一句话想用一套代码管两端、并且让测试资产可以长期沉淀Appium 的综合性价比最高。原生驱动虽然快但意味着两套脚本、两拨维护人账算下来并不划算。录制回放看着省事用例一多维护难度会直线上升我不推荐作为主方案。2. 架构原理解析搞懂它跑起来的过程2.1 客户端、服务端和驱动的关系很多同学装完环境就埋头写脚本遇到报错就蒙圈根源是不理解 Appium 的分层结构。我常用一个比喻解释Appium 是餐厅的服务员。你的测试脚本是顾客用固定的菜单格式点菜这个格式叫 WebDriver 协议服务员接单后把需求翻译给后厨后厨就是各平台的自动化驱动——Android 上默认是 UIAutomator2iOS 上是 XCUITest后厨做完菜再由服务员端回来。你的脚本只管和服务员沟通不用操心后厨怎么做菜。所以一次完整的自动化执行实际是这个链路测试脚本通过 Python/Java 客户端发起 HTTP 请求到 Appium 服务端Appium 服务端默认在 4723 端口监听接收请求后解析参数根据请求里的能力参数选择对应的平台驱动并创建会话驱动调用系统底层的自动化能力执行点击、滑动、截图、输入等动作执行结果沿原路返回脚本拿到返回值后断言或继续下一步。这个认知特别重要。以后排查问题时你先要判断报错出在哪一层是脚本层、协议层、服务端还是设备/驱动层。方向对了解决只是时间问题。我见过有人花一下午排查了半天最后发现只是 Appium 服务没启动就是因为没养成这个判断习惯。2.2 Desired Capabilities会话的第一步Desired Capabilities 说白了就是告诉 Appium我想测什么、怎么测的一组键值对。这是创建会话时必传的东西我把它理解为开单时的身份证信息。举个例子一个典型的 Android 能力配置是caps { platformName: Android, appium:platformVersion: 13, appium:deviceName: Android, appium:automationName: UiAutomator2, appium:appPackage: com.example.demo, appium:appActivity: .MainActivity, appium:noReset: True, }几个关键参数说一下platformName平台必填值是 Android 或 iOSappium:automationName驱动名称Android 用 UiAutomator2iOS 用 XCUITestappPackage 和 appActivityAndroid 必填的一对分别代表被测应用的包名和入口界面noReset是否不重置应用数据。调试时设成 True 能省很多登录步骤但用例要保障独立性时得结合 reset 策略仔细设计。注意 Appium 2.x 之后凡是 Appium 自有参数官方规范推荐加 appium: 前缀客户端库通常也能兼容旧写法但新项目建议直接按新规范来。2.3 元素定位所有操作的基础脚本能不能稳定地找到一个按钮决定了框架的生死。Appium 支持多种定位策略按我的使用频率排序resource-idAndroid 的 id唯一性最好优先用accessibility_id适合辅助功能标签规范的应用跨平台一致性不错xpath灵活但脆弱页面一调整大概率要改尽量放后面class name、文本定位等辅助手段一般不作为主策略。一个很实用的习惯先在界面上把 id 定位到能用的元素不要一上来就糊 xpath。某次我在一个表单页用 xpath 写了三条用例下个版本文本框结构一改三条全部红掉。换成 id 之后页面再怎么重排只要语义没变用例基本不受影响。这就是为什么框架设计阶段我一直坚持把定位信息集中维护而不是散落在用例里。3. 环境搭建实操从零跑通第一个脚本3.1 环境准备清单搭建 Appium 测试环境本质上就是一条软件链JDK → Android SDK → Node.js → Appium 服务端 → 平台驱动 → 客户端库 → 设备连接。每一步都要版本匹配我列一下我们项目里验证过的组合组件版本建议作用JDK8 或 11 均可Android 工具链和部分客户端依赖Android SDK较新版本platform-tools 必须装提供 adb、uiautomator 等能力Node.js14 及以上运行 Appium 服务端Appium2.x测试框架核心服务Python3.7 及以上我们选用的脚本语言Appium-Python-Client最新稳定版Python 语言客户端之所以 JDK 和 Android SDK 缺一不可是因为 UiAutomator2 驱动在解析页面、执行操作时会依赖 Android 系统工具链。如果只是先跑通 iOS 端JDK 也可以不装但绝大多数团队都是从 Android 起步所以这条链还是完整配齐更省心。3.2 安装 Appium 服务端和平台驱动Appium 2.x 安装很简单一条 npm 全局命令搞定npm install -g appium装完验证一下版本appium --version紧接着关键一步安装平台驱动。Appium 2.x 把平台驱动和核心服务做了拆分不装驱动的话起服务没问题但创建会话时会直接报找不到对应驱动。Android 默认驱动是 UIAutomator2执行appium driver install uiautomator2这个过程可能需要一点时间如果下载超时检查一下 npm 源配置或者换到网络空闲时段再试。装好后可以用appium driver list确认状态。最后启动服务端默认监听 4723 端口appium看到类似Appium server listening on 4723的输出就说明服务端准备好了。注意 Appium 2.x 兼容旧版的 /wd/hub 路径但有些新版本默认会使用根路径写客户端远程地址时如果报 404可以去掉 /wd/hub 再试一次。3.3 安装 Python 客户端库我们是用 Python 写用例的所以安装客户端库pip install Appium-Python-Client装完可以用一个小技巧验证环境在 Python 交互环境里导入包不报错就说明安装成功。import appium print(appium.__version__)这里提一个常见坑客户端库版本不要盲目升级到最新。Appium 服务端、平台驱动、客户端库三者是独立发布的版本偶有不兼容。团队里如果已经有一套稳定的组合就锁住版本不要今天看到一个新版本就升一下这个亏我吃过升级后某应用内部控件无法获取回退版本才恢复。3.4 连接设备并启动第一个会话Android 设备分真机和模拟器两种。真机需要在系统设置的开发者选项里打开 USB 调试还可能需要安装对应机型驱动模拟器启动后一般自带 adb 支持比较省事。连接到电脑后执行adb devices能看到设备编号和 device 状态说明连接成功。如果命令找不到检查 Android SDK 的 platform-tools 目录是否加入了系统环境变量。接下来跑一个最简单的脚本目标是打开 App 并断言当前界面import time from appium import webdriver from appium.webdriver.common.appiumby import AppiumBy caps { platformName: Android, appium:deviceName: Android, appium:appPackage: com.example.demo, appium:appActivity: .MainActivity, appium:noReset: True, } driver webdriver.Remote(http://127.0.0.1:4723, caps) time.sleep(3) el driver.find_element(AppiumBy.ID, com.example.demo:id/tv_title) assert el.text 首页 driver.quit()第一次看到屏幕上 App 自动打开又自动退出那种感觉很爽但别高兴太早。这个脚本能跑通说明你的整条链路已经通了后面才是真正磨人的工程化阶段。这个简单验证脚本里我用了 sleep纯粹是为了快速看效果进入第 4 章的框架阶段等待策略要统一换成显式等待。4. 框架设计别把用例写成一本流水账4.1 分层是为了抗住版本迭代接触过很多测试同学他们写的自动化脚本长这样一个文件里从启动 App 到点击、断言、退出全部写完。功能一多文件几十个改一个元素定位要全局搜索替换。这种脚本用两周就会变成负资产。我建议的分层思路核心就三句把设备和会话管理放到公共层谁要用谁拿把页面元素和页面操作封装成页面对象用例不直接碰定位符把业务步骤组装放到用例层用例只描述用户视角。这样做的好处很直接当 UI 改版时只需要改对应页面对象里的内容用例主体完全不用动。维护成本从全工程搜索替换变成精准改一处这种差距在项目跑了半年后会特别明显。4.2 一个可以直接抄的目录结构我目前在用的项目结构大致是这样project/ ├── config/ │ └── caps.py ├── pages/ │ ├── base_page.py │ ├── login_page.py │ └── home_page.py ├── testcases/ │ ├── conftest.py │ └── test_login.py ├── utils/ │ ├── driver_manager.py │ └── report_util.py └── reports/config放能力参数、环境配置区分测试环境与预发环境pages页面对象层一个页面一个类类的内部只描述这个页面上的元素和操作testcases测试用例层一个业务链路对应一个用例文件utils工具层放驱动初始化、报告、日志等通用能力reports存放测试报告和失败截图。4.3 核心封装示例先看驱动管理它负责创建和复用会话# utils/driver_manager.py from appium import webdriver _base_url http://127.0.0.1:4723 def create_driver(caps: dict): return webdriver.Remote(_base_url, caps)再看页面对象的基类把元素定位、点击、输入这些通用动作统一封装子页面直接继承# pages/base_page.py from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC class BasePage: def __init__(self, driver): self.driver driver def find(self, by, locator, timeout10): wait WebDriverWait(self.driver, timeout) return wait.until(EC.presence_of_element_located((by, locator))) def click(self, by, locator): self.find(by, locator).click() def input_text(self, by, locator, text): self.find(by, locator).send_keys(text) def get_text(self, by, locator): return self.find(by, locator).text这样封装之后页面对象写起来就很清爽# pages/login_page.py from appium.webdriver.common.appiumby import AppiumBy from pages.base_page import BasePage class LoginPage(BasePage): username (AppiumBy.ID, com.example.demo:id/edit_account) password (AppiumBy.ID, com.example.demo:id/edit_password) login_btn (AppiumBy.ID, com.example.demo:id/btn_login) def login(self, user, pwd): self.input_text(*self.username, user) self.input_text(*self.password, pwd) self.click(*self.login_btn)用例层只需要描述用户行为# testcases/test_login.py import pytest from appium.webdriver.common.appiumby import AppiumBy from utils.driver_manager import create_driver from pages.login_page import LoginPage from config.caps import android_caps class TestLogin: def setup_method(self): self.driver create_driver(android_caps()) self.login_page LoginPage(self.driver) def teardown_method(self): self.driver.quit() def test_login_success(self): self.login_page.login(test_user, 123456) home_text self.login_page.get_text( AppiumBy.ID, com.example.demo:id/tv_welcome ) assert 欢迎 in home_text注意测试框架我们用的是 pytest它对断言、前置后置、测试报告的支持都很好是 Python 生态里做自动化测试的主流选择之一。4.4 这样设计后改动一个元素会怎样假设某个版本的登录按钮 id 变了你要做的只有一件事改 login_page.py 里那一行元组。用例文件、驱动管理、断言逻辑全部不动。对比一把梭的写法——登录按钮 id 可能出现在十个用例文件里你得逐个定位、逐个改、逐个回归。这种差距就是框架和脚本的本质区别。另外我强烈建议每条用例结束时都保留一张截图或一段页面源码用 driver.get_screenshot_as_file() 把失败时的界面状态留下来。很多同学嫌截图麻烦等用例红了几遍就会明白这东西是真香。5. 常见问题与排查技巧实录5.1 会话建立失败、设备连不上这是新手遇到最多的坑。先从三个方向查第一Appium 服务是否真的在跑。命令行看 4723 端口有没有监听很多人是脚本开了但服务没起报错信息全是 Request error。第二adb 是否识别设备。执行 adb devices如果设备状态是 unauthorized说明手机上的调试授权还没点允许如果完全没显示检查 USB 调试是否打开、数据线是否只充电不传数据。第三驱动是否安装。Appium 2.x 如果没装对应平台驱动创建会话会直接报Could not find a driver。执行 appium driver list 确认缺了就 appium driver install uiautomator2 补上。5.2 元素定位不到一半是时机一半是策略定位不到元素时不要急着改 xpath。先问自己三个问题页面真的加载完了吗很多页面是异步渲染的元素要等网络请求返回后才出现在界面树里这个元素是不是在 WebView 里混合应用的前端页面不能直接用原生定位方式可能需要切换上下文id 是不是动态生成的有些 App 的列表项 id 每次启动都变这种只能换相对定位。处理思路也有先后顺序先用显式等待确认时机问题再看元素树结构最后才考虑换定位策略。我见过不少人上来就把 xpath 改来改去问题根本没解决因为根因是没等到元素出现。5.3 用例时好时坏稳定性的几个隐形杀手用例不稳定是自动化框架从能跑走向能用之间最大的坎。我复盘过自己项目里那些时不时红的用例原因集中在四类等待策略混乱隐式等待和显式等待混用导致某些元素等得不够或等得重复用例之间有数据依赖上一条用例留下的登录态或脏数据污染了下一条设备性能波动旧手机上动画没结束脚本就去点击被系统拦截全局弹窗干扰比如首次安装的权限弹窗、升级提示把这些意外当作预期处理了。针对这些我们的做法是统一用显式等待尽量少用固定 sleep每条用例入口状态自己保证避免跨用例依赖执行前关闭所有通知、关闭动画把权限弹窗的处理封装成本地工具在需要时自动点击允许。5.4 问题速查表现象常见原因处理建议appium 命令找不到Node.js 全局目录不在 PATH重装并配置 npm 全局路径adb devices 无设备USB 调试没开/驱动问题重插线、重启 adb server、装驱动创建会话超时Appium 服务或驱动问题看服务端日志确认驱动列表点击没有反应元素被遮挡/动画未完成用显式等待必要时先校验可点击状态元素树里找不到控件WebView/动态 id切换上下文改用相对定位脚本时好时坏等待/数据残留/弹窗干扰专项排查参考 5.3这张表是我平时排查问题时的模板也可以作为团队内部的知识库起点遇到新问题就往里补充。6. 稳定性提升与 CI 集成经验6.1 等待策略的统一稳定性的核心很大程度上是时机管理。Appium 提供了隐式等待和显式等待两种方式我的建议非常明确工程化项目里统一使用显式等待。原因是隐式等待是全局的它只能解决元素出现的等待解决不了元素可点击这类状态问题。显式等待则可以精确到某个条件比如元素可见、可点击、文本变化等。在页面对象层的 find 方法里可以加入可点击判断def wait_clickable(self, by, locator, timeout10): wait WebDriverWait(self.driver, timeout) return wait.until(EC.element_to_be_clickable((by, locator)))点击操作优先走 wait_clickable而不是简单的 find 之后立刻 click。这个改动看着不起眼但确实能让点击类的用例稳定性上升一个台阶。6.2 用例独立性和失败自愈自动化最忌用例之间互相依赖。我推崇的用例设计原则是每一条用例都能从干净的初始状态出发结束时不留下影响后续用例的脏数据。实现手段上Android 可以通过启动参数做数据清理或者在执行前置里重置应用状态。如果被测应用没有提供测试接口那就至少保证用例内的数据不跨用例共享登录账号各用各的避免上一条用例把账号锁了后一条跟着失败。另外失败重试机制可以放在执行框架层。我们的做法是连续失败超过两次才判定失败单次偶发失败自动重跑一次并把重试标记写入报告。这套机制能把最终报告的有效性提高不少不用半夜爬起来看一两条偶发失败。6.3 把脚本交给持续集成平台脚本能本地跑通只是一半真正的价值是定时执行、没有人值守。我们的做法是接到持续集成平台上每天晚上触发一次回归任务跑完自动生成报告并推送到工作群里。接入持续集成时要注意几点任务机上要保持 Appium 服务可用建议由 CI 任务在用例执行前统一启动结束后统一关闭测试报告和截图要归档按日期和分支保留执行机资源要足够多个任务并行时设备池和端口要提前规划避免设备冲突。这套跑起来之后我们核心链路的回归时间从原来手工的半天缩短到自动化任务不到一个小时而且因为人不在场用例的稳定性要求反而被倒逼着提高了。最后分享一点个人这些年积累下来的感受Appium 框架不是装完环境写几百个用例就算成功真正的分水岭在于能不能长期稳定地跑下去。而长期稳定这件事没有太多捷径就是靠规范的架构、严格的等待策略、持续的用例维护一点点换来的。如果你刚起步不要追求一步到位先把最简单的链路跑通再慢慢往里面加页面对象、加报告、加 CI框架是会跟着项目一起长大的。希望这篇指南能帮你少踩几个坑。 
长河君 · 2026/10/20 17:29:14 · 阅读 1.2k Appium移动端UI自动化测试框架搭建指南：从环境配置到稳定性优化
做移动端测试这些年前前后后搭过不下五套 UI 自动化的方案最后留在项目里长期跑的还是 Appium 移动端 UI 自动化测试框架。简单说它就是一套让脚本模拟手指点击、滑动、输入、断言的测试工具覆盖 Android 和 iOS官方和社区还维护了 Python、Java、JavaScript 等多种语言的客户端库同一套能力可以跨平台复用。这篇指南我会把从零搭建整套框架的流程讲透包括环境准备、架构原理、代码分层、问题排查和稳定性经验全程只讲实测可复现的做法适合刚开始接触移动端自动化、准备在团队里正式落地框架的测试工程师也适合已经写过几个脚本、但想把它工程化和规范化的同学。先给个忠告框架这件事想清楚再动手比急着敲命令重要得多。1. 为什么选 Appium先回答三个问题1.1 它到底解决了什么问题移动端回归测试有个老大难版本迭代快、兼容矩阵多、手工回归费人。Appium 解决的正是用机器替代人重复劳动的问题——冒烟测试、核心链路回归、多机型兼容性验证都能交给脚本在夜间执行第二天早上直接看报告。它有四个特性是当初我们在某项目组选型时最看重的跨平台同一套 API 操作 Android 和 iOS底层驱动自动切换不用为每个平台单独写一套跨语言Python、Java、Ruby、JavaScript 都有官方客户端团队熟悉什么语言就用什么不需要全员转语言黑盒驱动不依赖被测应用的源码只要 App 能装、能跑就能测对研发团队来说接入成本低生态成熟社区资料量很大踩过的坑基本都能搜到现成方案这一点在技术选型里非常重要。我见过不少团队一上来就追求大而全结果用例跑两天就垮。所以这里先明确Appium 不是银弹。它适合产品形态相对稳定、有持续迭代节奏、且团队愿意长期维护测试代码的场景。反过来如果项目面向核心功能频繁改版或者团队连一个专职自动化的人都没有那建议先不要上手工探索性测试加上简单的脚本巡检反而划算。1.2 和同类方案对比后为什么仍选它选型阶段我们对比过几个方向平台官方推荐的原生驱动方案、录制回放类工具以及各类云真机平台。这里放一张基于我们实际使用感受的对比表方案跨平台执行速度维护成本适用场景Appium好中等中高跨平台回归、端到端流程验证平台原生驱动差按平台分开快中等单平台深度专项、性能验证录制回放工具一般快高临时冒烟不适合规模化沉淀云真机平台好中等低按量付费多机型覆盖、线下设备不足结论就一句话想用一套代码管两端、并且让测试资产可以长期沉淀Appium 的综合性价比最高。原生驱动虽然快但意味着两套脚本、两拨维护人账算下来并不划算。录制回放看着省事用例一多维护难度会直线上升我不推荐作为主方案。2. 架构原理解析搞懂它跑起来的过程2.1 客户端、服务端和驱动的关系很多同学装完环境就埋头写脚本遇到报错就蒙圈根源是不理解 Appium 的分层结构。我常用一个比喻解释Appium 是餐厅的服务员。你的测试脚本是顾客用固定的菜单格式点菜这个格式叫 WebDriver 协议服务员接单后把需求翻译给后厨后厨就是各平台的自动化驱动——Android 上默认是 UIAutomator2iOS 上是 XCUITest后厨做完菜再由服务员端回来。你的脚本只管和服务员沟通不用操心后厨怎么做菜。所以一次完整的自动化执行实际是这个链路测试脚本通过 Python/Java 客户端发起 HTTP 请求到 Appium 服务端Appium 服务端默认在 4723 端口监听接收请求后解析参数根据请求里的能力参数选择对应的平台驱动并创建会话驱动调用系统底层的自动化能力执行点击、滑动、截图、输入等动作执行结果沿原路返回脚本拿到返回值后断言或继续下一步。这个认知特别重要。以后排查问题时你先要判断报错出在哪一层是脚本层、协议层、服务端还是设备/驱动层。方向对了解决只是时间问题。我见过有人花一下午排查了半天最后发现只是 Appium 服务没启动就是因为没养成这个判断习惯。2.2 Desired Capabilities会话的第一步Desired Capabilities 说白了就是告诉 Appium我想测什么、怎么测的一组键值对。这是创建会话时必传的东西我把它理解为开单时的身份证信息。举个例子一个典型的 Android 能力配置是caps { platformName: Android, appium:platformVersion: 13, appium:deviceName: Android, appium:automationName: UiAutomator2, appium:appPackage: com.example.demo, appium:appActivity: .MainActivity, appium:noReset: True, }几个关键参数说一下platformName平台必填值是 Android 或 iOSappium:automationName驱动名称Android 用 UiAutomator2iOS 用 XCUITestappPackage 和 appActivityAndroid 必填的一对分别代表被测应用的包名和入口界面noReset是否不重置应用数据。调试时设成 True 能省很多登录步骤但用例要保障独立性时得结合 reset 策略仔细设计。注意 Appium 2.x 之后凡是 Appium 自有参数官方规范推荐加 appium: 前缀客户端库通常也能兼容旧写法但新项目建议直接按新规范来。2.3 元素定位所有操作的基础脚本能不能稳定地找到一个按钮决定了框架的生死。Appium 支持多种定位策略按我的使用频率排序resource-idAndroid 的 id唯一性最好优先用accessibility_id适合辅助功能标签规范的应用跨平台一致性不错xpath灵活但脆弱页面一调整大概率要改尽量放后面class name、文本定位等辅助手段一般不作为主策略。一个很实用的习惯先在界面上把 id 定位到能用的元素不要一上来就糊 xpath。某次我在一个表单页用 xpath 写了三条用例下个版本文本框结构一改三条全部红掉。换成 id 之后页面再怎么重排只要语义没变用例基本不受影响。这就是为什么框架设计阶段我一直坚持把定位信息集中维护而不是散落在用例里。3. 环境搭建实操从零跑通第一个脚本3.1 环境准备清单搭建 Appium 测试环境本质上就是一条软件链JDK → Android SDK → Node.js → Appium 服务端 → 平台驱动 → 客户端库 → 设备连接。每一步都要版本匹配我列一下我们项目里验证过的组合组件版本建议作用JDK8 或 11 均可Android 工具链和部分客户端依赖Android SDK较新版本platform-tools 必须装提供 adb、uiautomator 等能力Node.js14 及以上运行 Appium 服务端Appium2.x测试框架核心服务Python3.7 及以上我们选用的脚本语言Appium-Python-Client最新稳定版Python 语言客户端之所以 JDK 和 Android SDK 缺一不可是因为 UiAutomator2 驱动在解析页面、执行操作时会依赖 Android 系统工具链。如果只是先跑通 iOS 端JDK 也可以不装但绝大多数团队都是从 Android 起步所以这条链还是完整配齐更省心。3.2 安装 Appium 服务端和平台驱动Appium 2.x 安装很简单一条 npm 全局命令搞定npm install -g appium装完验证一下版本appium --version紧接着关键一步安装平台驱动。Appium 2.x 把平台驱动和核心服务做了拆分不装驱动的话起服务没问题但创建会话时会直接报找不到对应驱动。Android 默认驱动是 UIAutomator2执行appium driver install uiautomator2这个过程可能需要一点时间如果下载超时检查一下 npm 源配置或者换到网络空闲时段再试。装好后可以用appium driver list确认状态。最后启动服务端默认监听 4723 端口appium看到类似Appium server listening on 4723的输出就说明服务端准备好了。注意 Appium 2.x 兼容旧版的 /wd/hub 路径但有些新版本默认会使用根路径写客户端远程地址时如果报 404可以去掉 /wd/hub 再试一次。3.3 安装 Python 客户端库我们是用 Python 写用例的所以安装客户端库pip install Appium-Python-Client装完可以用一个小技巧验证环境在 Python 交互环境里导入包不报错就说明安装成功。import appium print(appium.__version__)这里提一个常见坑客户端库版本不要盲目升级到最新。Appium 服务端、平台驱动、客户端库三者是独立发布的版本偶有不兼容。团队里如果已经有一套稳定的组合就锁住版本不要今天看到一个新版本就升一下这个亏我吃过升级后某应用内部控件无法获取回退版本才恢复。3.4 连接设备并启动第一个会话Android 设备分真机和模拟器两种。真机需要在系统设置的开发者选项里打开 USB 调试还可能需要安装对应机型驱动模拟器启动后一般自带 adb 支持比较省事。连接到电脑后执行adb devices能看到设备编号和 device 状态说明连接成功。如果命令找不到检查 Android SDK 的 platform-tools 目录是否加入了系统环境变量。接下来跑一个最简单的脚本目标是打开 App 并断言当前界面import time from appium import webdriver from appium.webdriver.common.appiumby import AppiumBy caps { platformName: Android, appium:deviceName: Android, appium:appPackage: com.example.demo, appium:appActivity: .MainActivity, appium:noReset: True, } driver webdriver.Remote(http://127.0.0.1:4723, caps) time.sleep(3) el driver.find_element(AppiumBy.ID, com.example.demo:id/tv_title) assert el.text 首页 driver.quit()第一次看到屏幕上 App 自动打开又自动退出那种感觉很爽但别高兴太早。这个脚本能跑通说明你的整条链路已经通了后面才是真正磨人的工程化阶段。这个简单验证脚本里我用了 sleep纯粹是为了快速看效果进入第 4 章的框架阶段等待策略要统一换成显式等待。4. 框架设计别把用例写成一本流水账4.1 分层是为了抗住版本迭代接触过很多测试同学他们写的自动化脚本长这样一个文件里从启动 App 到点击、断言、退出全部写完。功能一多文件几十个改一个元素定位要全局搜索替换。这种脚本用两周就会变成负资产。我建议的分层思路核心就三句把设备和会话管理放到公共层谁要用谁拿把页面元素和页面操作封装成页面对象用例不直接碰定位符把业务步骤组装放到用例层用例只描述用户视角。这样做的好处很直接当 UI 改版时只需要改对应页面对象里的内容用例主体完全不用动。维护成本从全工程搜索替换变成精准改一处这种差距在项目跑了半年后会特别明显。4.2 一个可以直接抄的目录结构我目前在用的项目结构大致是这样project/ ├── config/ │ └── caps.py ├── pages/ │ ├── base_page.py │ ├── login_page.py │ └── home_page.py ├── testcases/ │ ├── conftest.py │ └── test_login.py ├── utils/ │ ├── driver_manager.py │ └── report_util.py └── reports/config放能力参数、环境配置区分测试环境与预发环境pages页面对象层一个页面一个类类的内部只描述这个页面上的元素和操作testcases测试用例层一个业务链路对应一个用例文件utils工具层放驱动初始化、报告、日志等通用能力reports存放测试报告和失败截图。4.3 核心封装示例先看驱动管理它负责创建和复用会话# utils/driver_manager.py from appium import webdriver _base_url http://127.0.0.1:4723 def create_driver(caps: dict): return webdriver.Remote(_base_url, caps)再看页面对象的基类把元素定位、点击、输入这些通用动作统一封装子页面直接继承# pages/base_page.py from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC class BasePage: def __init__(self, driver): self.driver driver def find(self, by, locator, timeout10): wait WebDriverWait(self.driver, timeout) return wait.until(EC.presence_of_element_located((by, locator))) def click(self, by, locator): self.find(by, locator).click() def input_text(self, by, locator, text): self.find(by, locator).send_keys(text) def get_text(self, by, locator): return self.find(by, locator).text这样封装之后页面对象写起来就很清爽# pages/login_page.py from appium.webdriver.common.appiumby import AppiumBy from pages.base_page import BasePage class LoginPage(BasePage): username (AppiumBy.ID, com.example.demo:id/edit_account) password (AppiumBy.ID, com.example.demo:id/edit_password) login_btn (AppiumBy.ID, com.example.demo:id/btn_login) def login(self, user, pwd): self.input_text(*self.username, user) self.input_text(*self.password, pwd) self.click(*self.login_btn)用例层只需要描述用户行为# testcases/test_login.py import pytest from appium.webdriver.common.appiumby import AppiumBy from utils.driver_manager import create_driver from pages.login_page import LoginPage from config.caps import android_caps class TestLogin: def setup_method(self): self.driver create_driver(android_caps()) self.login_page LoginPage(self.driver) def teardown_method(self): self.driver.quit() def test_login_success(self): self.login_page.login(test_user, 123456) home_text self.login_page.get_text( AppiumBy.ID, com.example.demo:id/tv_welcome ) assert 欢迎 in home_text注意测试框架我们用的是 pytest它对断言、前置后置、测试报告的支持都很好是 Python 生态里做自动化测试的主流选择之一。4.4 这样设计后改动一个元素会怎样假设某个版本的登录按钮 id 变了你要做的只有一件事改 login_page.py 里那一行元组。用例文件、驱动管理、断言逻辑全部不动。对比一把梭的写法——登录按钮 id 可能出现在十个用例文件里你得逐个定位、逐个改、逐个回归。这种差距就是框架和脚本的本质区别。另外我强烈建议每条用例结束时都保留一张截图或一段页面源码用 driver.get_screenshot_as_file() 把失败时的界面状态留下来。很多同学嫌截图麻烦等用例红了几遍就会明白这东西是真香。5. 常见问题与排查技巧实录5.1 会话建立失败、设备连不上这是新手遇到最多的坑。先从三个方向查第一Appium 服务是否真的在跑。命令行看 4723 端口有没有监听很多人是脚本开了但服务没起报错信息全是 Request error。第二adb 是否识别设备。执行 adb devices如果设备状态是 unauthorized说明手机上的调试授权还没点允许如果完全没显示检查 USB 调试是否打开、数据线是否只充电不传数据。第三驱动是否安装。Appium 2.x 如果没装对应平台驱动创建会话会直接报Could not find a driver。执行 appium driver list 确认缺了就 appium driver install uiautomator2 补上。5.2 元素定位不到一半是时机一半是策略定位不到元素时不要急着改 xpath。先问自己三个问题页面真的加载完了吗很多页面是异步渲染的元素要等网络请求返回后才出现在界面树里这个元素是不是在 WebView 里混合应用的前端页面不能直接用原生定位方式可能需要切换上下文id 是不是动态生成的有些 App 的列表项 id 每次启动都变这种只能换相对定位。处理思路也有先后顺序先用显式等待确认时机问题再看元素树结构最后才考虑换定位策略。我见过不少人上来就把 xpath 改来改去问题根本没解决因为根因是没等到元素出现。5.3 用例时好时坏稳定性的几个隐形杀手用例不稳定是自动化框架从能跑走向能用之间最大的坎。我复盘过自己项目里那些时不时红的用例原因集中在四类等待策略混乱隐式等待和显式等待混用导致某些元素等得不够或等得重复用例之间有数据依赖上一条用例留下的登录态或脏数据污染了下一条设备性能波动旧手机上动画没结束脚本就去点击被系统拦截全局弹窗干扰比如首次安装的权限弹窗、升级提示把这些意外当作预期处理了。针对这些我们的做法是统一用显式等待尽量少用固定 sleep每条用例入口状态自己保证避免跨用例依赖执行前关闭所有通知、关闭动画把权限弹窗的处理封装成本地工具在需要时自动点击允许。5.4 问题速查表现象常见原因处理建议appium 命令找不到Node.js 全局目录不在 PATH重装并配置 npm 全局路径adb devices 无设备USB 调试没开/驱动问题重插线、重启 adb server、装驱动创建会话超时Appium 服务或驱动问题看服务端日志确认驱动列表点击没有反应元素被遮挡/动画未完成用显式等待必要时先校验可点击状态元素树里找不到控件WebView/动态 id切换上下文改用相对定位脚本时好时坏等待/数据残留/弹窗干扰专项排查参考 5.3这张表是我平时排查问题时的模板也可以作为团队内部的知识库起点遇到新问题就往里补充。6. 稳定性提升与 CI 集成经验6.1 等待策略的统一稳定性的核心很大程度上是时机管理。Appium 提供了隐式等待和显式等待两种方式我的建议非常明确工程化项目里统一使用显式等待。原因是隐式等待是全局的它只能解决元素出现的等待解决不了元素可点击这类状态问题。显式等待则可以精确到某个条件比如元素可见、可点击、文本变化等。在页面对象层的 find 方法里可以加入可点击判断def wait_clickable(self, by, locator, timeout10): wait WebDriverWait(self.driver, timeout) return wait.until(EC.element_to_be_clickable((by, locator)))点击操作优先走 wait_clickable而不是简单的 find 之后立刻 click。这个改动看着不起眼但确实能让点击类的用例稳定性上升一个台阶。6.2 用例独立性和失败自愈自动化最忌用例之间互相依赖。我推崇的用例设计原则是每一条用例都能从干净的初始状态出发结束时不留下影响后续用例的脏数据。实现手段上Android 可以通过启动参数做数据清理或者在执行前置里重置应用状态。如果被测应用没有提供测试接口那就至少保证用例内的数据不跨用例共享登录账号各用各的避免上一条用例把账号锁了后一条跟着失败。另外失败重试机制可以放在执行框架层。我们的做法是连续失败超过两次才判定失败单次偶发失败自动重跑一次并把重试标记写入报告。这套机制能把最终报告的有效性提高不少不用半夜爬起来看一两条偶发失败。6.3 把脚本交给持续集成平台脚本能本地跑通只是一半真正的价值是定时执行、没有人值守。我们的做法是接到持续集成平台上每天晚上触发一次回归任务跑完自动生成报告并推送到工作群里。接入持续集成时要注意几点任务机上要保持 Appium 服务可用建议由 CI 任务在用例执行前统一启动结束后统一关闭测试报告和截图要归档按日期和分支保留执行机资源要足够多个任务并行时设备池和端口要提前规划避免设备冲突。这套跑起来之后我们核心链路的回归时间从原来手工的半天缩短到自动化任务不到一个小时而且因为人不在场用例的稳定性要求反而被倒逼着提高了。最后分享一点个人这些年积累下来的感受Appium 框架不是装完环境写几百个用例就算成功真正的分水岭在于能不能长期稳定地跑下去。而长期稳定这件事没有太多捷径就是靠规范的架构、严格的等待策略、持续的用例维护一点点换来的。如果你刚起步不要追求一步到位先把最简单的链路跑通再慢慢往里面加页面对象、加报告、加 CI框架是会跟着项目一起长大的。希望这篇指南能帮你少踩几个坑。