安卓定位器迁移：规则转换与模型实测

把 Android 自动化测试里的 XPath 换成 UiSelector，难点不在改字符串，而在保证它仍然找到同一批元素。作者做了转换器，又让 Claude Opus、Sonnet、Haiku 5.5 做同一道题：没有规则时，模型交出的答案有 7–9 % 会选错；补上规则后，错误降到 1–4 个，仍未超过转换器。

这篇值得读的地方，是它把 AI 编程里一个常见问题测了出来：代码看着合理、服务端也接受，不代表行为等价。对于批量迁移，明确规则、验证边界和保留跳过机制，比一次生成多少代码更重要。

UiSelector 更快，但迁移收益不止是速度

使用 Appium UiAutomator2 driver 时，XPath 查询会先把 UI 树序列化成 XML，再执行查询。UiSelector 对应 -android uiautomator 策略，直接遍历实时树；调用 findElement 时，找到第一个匹配项就停止。

作者在合成应用上测试了 30 个用例，即 10 种 XPath 形态乘以 3 个目标，界面规模从 100 到 2000 个元素。UiSelector 全胜，但不是网上常说的快 10–50 倍：单次查询节省 22–133 ms，相对收益从 49 % 降到 12 %。

更实际的差异是深度。驱动默认 snapshotMaxDepth 为 70，更深的节点不会进入 XPath 使用的快照。在 100 层的链式界面里，XPath 最深找到第 66 层标记，UiSelector 找到了第 100 层。

不过，这些速度数据来自模拟器上的单个 View 应用，Compose 和 WebView 没测。迁移是否划算，需要看自己的测试套件，不能直接套用百分比。

最危险的错误，是 API 名字相似、行为不同

contains(@text,"Total") 转成 textContains("Total")，看起来顺理成章。问题是 XPath 这里区分大小写，textContains 和 textStartsWith 却忽略大小写。前者不匹配「TOTAL」，后者会。

如果页面新增一个「TOTAL」标题，位置又在「Total: $5」之前，findElement 就可能点中另一个元素。作者采用的严格转换是 textMatches("(?s).*Total.*")，其中 (?s) 让正则里的点号也能匹配换行。

类似陷阱还有几个：

• childSelector 搜索任意后代，并不表示直接子节点；fromParent 搜索的是兄弟节点。
• childSelector 内的 instance() 按容器计数，不能直接代替全屏结果的位置索引。
• Appium 接收的是类似 Java 的字符串，服务端字符串字面量只反转义 \"。照搬 Java 的双反斜杠规则，可能让正则匹配不到元素。
• //* 的精确形式是 new UiSelector()；改成 classNameMatches(".*")，findElements 内部按 index(i) 遍历时会丢元素。
• 驱动默认支持 XPath 2.0，除非设置了 enforceXPath1。把 matches()、ends-with()、lower-case() 都当成不支持，也会误判。

批量迁移的验收标准，应当是行为等价，而不只是语法有效。

作者的转换器会连同策略调用一起改写，下面这段同时展示了位置转换、大小写处理和无法精确表达时的跳过：

- AppiumBy.xpath("(//android.widget.TextView[@content-desc='price'])[2]")
+ AppiumBy.androidUIAutomator("new UiSelector().className(\"android.widget.TextView\").description(\"price\").instance(1)")

- (AppiumBy.XPATH, '//*[@content-desc="Cart" and contains(@text, "USD")]')
+ (AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().description("Cart").textMatches("(?s).*USD.*")')

[skip] UiSelector has no direct-child criterion: //android.widget.ListView/android.widget.TextView[1]

重点看最后一行：UiSelector 没有直接子节点条件，工具选择留下原因，而不是硬凑一个近似答案。

结果分为 exact、close、skip。exact 要求元素及顺序一致；close 可能只保证首个元素相同，列表不完全一致。默认会输出 exact 和带警告的 close，--exact 才只保留精确转换。--loose 允许忽略大小写、把直接子节点放宽为后代等处理，并标成 close。

Claude 的成绩说明了什么，又没有说明什么

转换器先有验证，再有实现：作者在转换器出现前，就写了 170 个边界用例，其中 6 个用于 --loose，并在模拟器上比较两种定位器的结果。

随后，他们收集了 20 个开源 Appium 项目的 1645 个 XPath。默认可转换 73 %，其中 64 % exact、9 % close；--loose 可提高到 77 %。转换结果涉及 1169 个不同 XPath，在随机界面和针对条件构造的干扰界面上未发现错误。另用 1718 个故意写错的 UiSelector 检验测试能力，捕获率为 99.5 %。

模型对照使用其中另一组明确划定的样本：680 个 XPath，包括 149 个边界用例、19 个项目的 531 个真实定位器。Claude Code CLI 在空目录运行，只开放 Read、Write，effort medium，每个模型每轮只跑一次。

计分也偏向保守：正确得 1 分，close 得 0.5 分，跳过得 0 分，错误扣 1 分。转换器的 471.5 分作为 100 % 基准。

无规则时，Opus、Sonnet、Haiku 分别错了 47、60、63 个。三次共 170 个错误，其中 65 个是把 contains() 换成 textContains。即便接受这种大小写放宽，仍至少错 27、37、41 个。

作者再加入约 8000 字符的 rules.md，不提供具体题目答案，错误就降为 Opus、Sonnet 各 1 个，Haiku 4 个。Opus 用时约减半，成本降到 60 %，思考量降到四分之一。剩余问题包括 string-length(@text)=5 转成 textMatches("(?s).{5}") 时，ICU 的点号会把 CR LF 当成一个字符。

规则有效，但成绩存在明显前提：规则来自同一批 680 个样本暴露的错误，没有独立测试集，也没有充分重复运行。

模型也反过来改进了转换器。Opus 找出了滑块值只存在于 page source 导致的误判；六轮运行还找到 8 个原本跳过、实际可以精确转换的定位器，涉及 normalize-space()、string-length()、translate()、if … then … else 等。作者验证并补入后，模型才在所有定位器上都没有超过转换器。

我的判断

我认可「确定性工具先处理，模型再看剩余项」的分工。转换器免费、离线、无依赖，680 个定位器不到一秒完成，还能重复得到同样结果。模型更适合解释跳过原因、提出改写方案，也能帮助发现规则遗漏。

但「模型不如转换器」不能读成普遍排名。最终转换器已经吸收模型发现的缺陷和新增规则；这是一次有用的工具迭代，也让最终比较带有针对样本修正的成分。

实验范围同样有限：Android 16 模拟器为主，部分检查用了 Android 17；环境是 M1 Pro 上的 AOSP、Google Play 镜像，Appium 3.8.0、UiAutomator2 driver 8.7.0。没有真机、旧 Android、OEM 系统，也只测默认驱动设置。allowInvisibleElements 等设置变化，都可能改变结论。

作者把 Android 比 iOS 更难归因于 API 语义差异，解释合理；但 iOS 的 676 个样本错 4–7 个，与 Android 的样本和 effort 设置并不完全一致，「约十倍」只能看方向。

迁移还涉及维护期限。按原文，Google 计划弃用并移除 UiSelector，但没有日期；UiAutomator 2.4.0（2026 年 7 月）仍包含它，驱动服务端捆绑的是 2.3.0，Appium 的替代方案尚未公布，相关问题 appium-uiautomator2-driver#812 仍开放。因此，它适合作为有回退路径的优化，不能当作长期稳定性承诺。

能拿来做什么

1. 有 Android Appium 测试的团队，可以先预览转换结果，优先检查高频查询和深层节点，再决定迁移范围。工具要求 Node.js 20+，下面两条命令分别用于预览和写入：

   npx xpath-to-uiselector ./tests          # preview the diff
   npx xpath-to-uiselector ./tests --write  # apply it
   

   注意第二行的 --write 才会保存；需要逐项审查时，用 --json 输出跳过原因和警告。

2. 对要求行为保持一致的迁移，先用 --exact。只有明确接受大小写放宽、后代范围扩大时，再考虑 --loose，并检查页面上是否存在竞争元素。

3. 让 Claude 处理 skip 时，把驱动规则放进提示词，并把结果视为待验证建议。原文中，Sonnet 5.5 在 medium 下与 Opus 同分、成本约一半，但这只是一轮实验的结果。

4. 在 JS/TS 或其他测试代码里合入定位器前，跑一次目标界面，再补一个容易选错的干扰元素。作者展示的错误多数不会报语法错，只在界面变化后悄悄找错目标。