第一次在搜索引擎里敲下 colibri跳出来的东西能铺满三屏有人搜到的是嵌入式计算机模块有人搜到的是 iOS UI 自动化测试库还有人搜到的是同名的小众工具和生物信息学脚本。蜂鸟这个词在西班牙语、葡萄牙语里读起来轻快好听于是各路开源作者都爱拿它当项目名结果就是同名撞车撞得七荤八素。我做移动端质量保障这块有些年头了这几年陆续接手的几个 App 项目里UI 自动化从一个写几条冒烟用例意思一下的配角慢慢变成了发版前的硬性关卡。在这个过程中最让我头疼的从来不是写不出用例而是写出来的用例跑十次挂三次。而 colibri 这个库正是我为了解决其中一类具体问题——同一个 accessibility identifier 对应多个元素时的定位与等待——而真正用起来的工具。这篇内容我打算把它掰开揉碎讲清楚它是什么、它补的是哪块短板、怎么接进工程、踩过哪些坑以及怎么把它放到持续集成的流水线里不掉链子。适合已经写过几条 XCUITest、被 flaky 用例折磨过的同学也适合完全没碰过 iOS UI 自动化、想找个切入点的新手。1. 先把这个名字说清楚colibri 到底指哪一摊事1.1 三个同名项目别装错库同名问题必须先解决不然文章看一半你发现我讲的根本不是你搜的那个东西浪费时间。以我的检索经验技术圈里叫 colibri 的东西主要集中在这几个方向一是嵌入式计算模块产品线这类产品通常是核心板形态插在自研载板上跑 Linux 或实时系统做工业控制、医疗设备、车载终端的团队会接触二是 iOS/macOS 平台的 UI 自动化辅助库基于 XCTest 体系做元素查询与操作封装这也是本文的主线三是一些零散的脚本工具、命令行小玩意和学术项目里的数据处理代码生命周期往往很短。判断自己该看哪一篇有个很简单的办法看你的工程里import的是什么。如果打开的是 Xcode 的 UI Testing Target写的是 Swift那你要找的就是第二个如果你面对的是交叉编译工具链、设备树、内核裁减那你该看的是第一个方向的内容。还有一类朋友是纯粹被搜索引擎带偏的本来想搜某款 macOS 上的轻量浏览器或者某个 PDF 阅读器结果落到了开发工具的地盘那直接关掉就行。我之所以强调这个辨析是因为最近两年我至少见过两次团队里有人把硬件模块的文档链接贴进 iOS 项目的技术方案里评审的时候才发现牛头不对马嘴。开源生态里同名不同物是很正常的现象麻烦的是搜索结果会混在一起GitHub 上的仓库也会互相抢占关键词。养成先看语言和依赖再看目录结构的习惯能省下大量试错时间。1.2 为什么 iOS 的 Colibri 值得单独拎出来UI 自动化这个领域从来不缺框架Appium、Maestro、Kaspresso、Detox各路方案各有各的拥趸。但那句话怎么说的越靠近系统底层的方案越稳。XCUITest 是苹果官方提供的能力跑在模拟器和真机上直接和辅助功能Accessibility体系打交道不需要额外的 WebDriver 服务也不需要跨进程通信的中间层。它的确定性是第三方方案很难比的。问题在于官方这套 API 把能力给得很足把顺手给得很吝啬。最典型的例子就是查询元素的链式写法app.tables.cells.matching(identifier: row).element(boundBy: 3)这一长串你得记住查询类型、匹配方式、下标还得自己处理元素还没出现的情况。业务代码里偶尔写一次无所谓当成千上万行测试代码里到处都是这种表达式时可读性和可维护性就开始崩了。colibri 的定位就是在这个缝隙里做事它不去替换 XCTest而是在 XCUITest 之上加一层薄薄的、语义更清晰的封装把常见的查询、等待、点击、输入操作收敛成更短更一致的调用方式尤其针对同 identifier 多元素这类高频场景做了简化。它不是银弹也解决不了被测 App 本身的随机性但它确实能减少一类特定代码噪音让测试代码的意图更直白。我个人的判断是如果你的项目里同一个 identifier 反复出现、测试代码里到处是element(boundBy:)那这个库就有引入价值如果你的页面元素 identifier 管理得很干净、几乎不存在重复那引入它带来的收益会很有限。2. 痛点拆解同 identifier 元素定位为什么这么难2.1 XCUITest 原生的查询模型到底怎么回事要理解 colibri 的价值得先把 XCTest 的查询模型捋清楚。整个体系是围绕元素树构建的App 启动后XCUITest 会通过辅助功能接口把当前界面抓成一棵层级树每个节点有类型Button、Cell、StaticText 等、identifier、label、value 等属性还有它的 frame。查询的本质就是在树上按条件筛选返回一个XCUIElementQuery再从这个 query 里取出具体的XCUIElement去操作。关键的坑在于XCUIElementQuery是一个惰性的、动态求值的对象它不缓存结果。每次你调用element(boundBy: n)它都会重新在当前的树快照上做一次筛选。这意味着两件事一是如果界面还在变化前后两次取到的可能是不同元素二是如果匹配到的元素数量少于你给的下标会直接抛异常或者返回一个永远不存在的元素测试就挂了。再往下说一层exists这个属性也是即时求值——它反映的是你读到它的那一瞬间元素在不在而不是元素会不会在接下来两秒内出现。很多新手写if element.exists { element.tap() }在动画还没结束的时候检查结果当然是 false然后测试静默地跳过了整个操作最后在断言阶段以一句毫无信息量的元素不存在失败。这就是典型的不稳定用例来源。2.2 三种常见错误写法与它们翻车的原因第一种直接下标硬编码。app.buttons.matching(identifier: item).element(boundBy: 0).tap()。看起来没问题但列表第一项的顺序可能因为服务端返回顺序变化、本地缓存差异、甚至排序规则的微调而改变。你依赖的是位置而位置在动态列表里是最不可靠的信息。第二种用firstMatch图省事。app.buttons[item].firstMatch在只有唯一元素时确实快因为它一旦找到第一个匹配就停止搜索性能上有优势。但如果页面上有三个同名按钮firstMatch选中的是树里最先被遍历到的那个未必是你视觉上认为的第一个也未必是用户会点的那个。这个坑特别隐蔽因为大部分时候它看起来是对的。第三种混淆identifier和label。app.buttons[xxx]这个下标写法实际上是按 identifier 优先、label 兜底去匹配的。当某天设计师把按钮文案从确定改成确认你的用例就全线飘红而你根本没动过测试代码。正确的做法是给所有需要交互的元素显式配置 accessibility identifier用稳定的人工编号而不是自然语言文案。这三种写法我在不同的项目里都见过而且往往是混着来的。你会发现问题都不在于写不出来而在于写出来的东西对上下文过于敏感。UI 测试的稳定性本质上是在和不确定性作斗争网络、动画、异步渲染、列表复用每一个都在制造不确定性。代码写得越贴近我确定要操作哪一个元素就越稳。2.3 Colibri 的封装思路与取舍理解了上面的痛点colibri 的取舍就很清楚了。它没有去发明一套新的元素描述语言也没有搞出跨平台抽象层而是做了三件事把冗长的 query 链式调用收敛成更短的入口把等待元素出现/消失和后续操作合并成一步避免忘记等待对重复 identifier 场景提供按顺序或按可见性选择元素的辅助方法。这种薄封装的路线有利有弊。好处是学习成本极低你原来会写 XCUITest看半小时就能上手出问题时也能直接退回原生 API 排查不存在黑盒。坏处是它不解决语义层面的问题——如果页面上五个元素的 identifier 全都叫cell库也猜不出你想点哪个仍然需要你给出下标或者别的筛选条件。指望引入一个库就让 flaky 测试变成零失败这个预期要先放下来。我在选型时有个习惯优先考虑能不能随时甩掉的工具。如果一个封装库突然停止维护或者某个版本引入了不兼容变更我能不能在半天内把项目切回原生写法colibri 这类薄封装的答案是能这也是我愿意在正式项目里用它的原因之一。反过来那些深度侵入业务代码、要求你按它的方式重构整个工程结构的框架我会更谨慎。3. 从零搭一个能跑的最小工程3.1 依赖接入与版本选择colibri 是一个纯 Swift 的库走 Swift Package Manager 接入是最省事的方式。具体操作是在 Xcode 里选中你的 UI Testing Target注意是测试 Target 而不是主 App Target然后在 Package Dependencies 里添加仓库地址地址以仓库首页为准这类小库偶尔会迁移。依赖规则建议用Up to Next Major Version因为这类封装库的 API 面不大大版本升级通常意味着方法签名有调整锁死小版本反而会错过修复。如果你所在的项目还在用 CocoaPods 统一管理依赖也可以走 pod 方式但要注意 UI 测试 Target 在 Podfile 里的 target 声明必须写对很多人踩过的坑是把依赖加到了主 App 上结果编译通过了但测试代码里import不到排查半天。判断方法很简单打开 Build Settings 里的 Framework Search Paths看依赖产物是不是挂在测试 Target 下面。接入之后建议先做一次空跑验证新建一个测试方法方法体里只放一句XCTAssertTrue(true)直接跑一次。这一步的目的是确认 Target 配置、签名、模拟器选择都没问题把环境问题和代码问题分开。我见过太多人一上来就写几十行用例失败了分不清是库没接好还是逻辑写错了白白浪费一下午。这个先跑通空壳的习惯是我做自动化的第一原则。3.2 示例工程与测试 Target 的配置要点为了让示例可复现我们先假定被测界面是一个列表页里面有若干个结构相同的行每行有一个标题文本、一个开关、一个进入详情的按钮。这个结构非常典型电商、资讯、设置页都是这个套路。三个元素的 accessibility identifier 分别设为feed_title、feed_switch、feed_detail也就是每一行都会重复出现这三个 identifier。这正是 colibri 的主场。在给元素配 identifier 之前有个前提条件必须确认这个元素是可访问的。如果一个自定义视图没有开启 isAccessibilityElement或者被上层容器吞掉了辅助功能信息那么无论你怎么配 identifierXCUITest 都看不到它。表现是查询结果永远是空的而且不会报错只是匹配不到。解决办法是在自定义控件的初始化里设置isAccessibilityElement true并给它一个合适的 accessibilityTraits让系统知道它是按钮还是文本。另外如果你的列表是 UITableView 或 UICollectionView单元格复用会让元素树里的节点顺序和出现时机变得微妙。同一个 identifier 在屏幕上可能对应多个可访问节点而不可见的复用池里的节点有时也会被算进去。这是很多明明只有三行为什么匹配到五个这类诡异现象的根源。后面讲排查技巧时我会给出定位方法。测试 Target 层面还要注意语言和区域设置。如果你的 App 做了多语言测试运行时的系统语言会影响 label 内容从而影响按 label 的匹配结果。稳妥做法是给测试 Target 设置固定的-AppleLanguages和-AppleLocale启动参数让每次运行的环境完全一致。这个设置不写本地跑通、CI 上挂掉是常有的事。3.3 第一条测试用例环境就绪后第一条用例我建议选最有代表性的点击列表第三行的详情按钮。代码大概长这样方法名以仓库最新文档为准思路是通用的import XCTest final class FeedListUITests: XCTestCase { private var app: XCUIApplication! override func setUpWithError() throws { continueAfterFailure false app XCUIApplication() app.launchArguments [-AppleLanguages, (zh-Hans), -AppleLocale, zh_CN] app.launch() } func testTapThirdRowDetail() throws { let detailButton app.buttons .matching(identifier: feed_detail) .element(boundBy: 2) XCTAssertTrue(detailButton.waitForExistence(timeout: 5), 第三行的详情按钮在 5 秒内没有出现) detailButton.tap() XCTAssertTrue(app.staticTexts[detail_title].waitForExistence(timeout: 5), 详情页标题没有加载出来) } }这几行代码里有三个值得说的细节。第一continueAfterFailure false要放在最早的位置它保证一条用例失败后立即停止避免后续操作在一堆报错上继续执行把真正的错误信息淹没。第二waitForExistence是必须的不能直接 tap因为 App 启动到列表渲染完成有时间差。第三失败时给的提示信息要写清楚是哪一行的哪个按钮因为将来定位问题时控制台里那句提示就是你唯一的线索。4. 核心能力逐项拆解4.1 查询与索引定位回到重复 identifier 的问题colibri 提供的价值在于把匹配 取下标这段逻辑变得更短、更统一。原生写法是matching(identifier:)加element(boundBy:)封装之后通常是一个链式方法就能取到目标元素可读性提升明显。但我要强调的是无论用哪种写法下标从哪来这个问题依然要你自己回答。下标取值有三条判断依据。第一条是屏幕上的视觉顺序这需要你确认元素树的遍历顺序和视觉顺序一致大多数纵向列表是一致的但遇到横向滚动或者复杂的嵌套容器就不一定。第二条是业务语义顺序比如取第一个未读的消息这种就不该用下标而应该通过元素的其他属性value、label 或者自定义标识来筛选。第三种是唯一标识理想情况下每行的 identifier 都带上业务 id比如feed_detail_1024这样完全不需要下标。我的建议是能做成唯一标识的一律做唯一标识实在做不了的比如纯位置相关的交互再用下标并且把下标定义为命名常量附上注释说明它对应哪个业务对象。这条规则看起来啰嗦但在项目进行到第三个月、业务方改了三版需求之后你会感谢当时写了注释的自己。4.2 等待、重试与超时分层UI 自动化里 90% 的随机失败都和时机有关。元素还没渲染完就操作、动画还没结束就断言、页面切换过程中查询了旧页面这些都会导致失败而且失败得毫无规律。解决思路是分层的不能一个固定 sleep 走天下。第一层是隐式等待也就是waitForExistence这类。它内部是轮询机制每隔一小段时间重新查询一次直到元素出现或者超时。这个超时值不要设得太短timeout: 1在 CI 机器上几乎等于碰运气也不要设得太长太长会让失败反馈延迟整体耗时长到没人愿意跑。我的经验值是本机开发时 5 秒起步CI 上乘 1.5 到 2 倍。第二层是操作前的状态确认。要点击的元素不仅需要存在还需要isHittable。存在但不可点击的情况太常见了元素被键盘遮挡、在滚动区域之外、被一个透明的遮罩层盖住。只判断exists就点击系统会尝试滚动或者直接报错这个行为在不同 iOS 版本上还有差异。稳妥做法是组合判断或者用封装库里更完整的可用性检查方法。第三层是整体超时。XCTest 有单个用例的超时上限超过就会被判定为超时失败。这个值在 CI 上建议放宽因为 CI 机器性能和模拟器启动速度都不稳定。同时要注意如果某个用例长期处于接近超时边缘它是潜在的不稳定点即使现在没挂也迟早会挂。定期统计每个用例的耗时分布把明显偏慢的那些挑出来优化是保持测试套件健康的有效手段。4.3 页面对象模式的落地姿势测试代码规模一旦上去最大的敌人就是重复。同一个元素在十个用例里被以相同的方式查询某天界面改了你要改十个地方。页面对象模式Page Object就是来解决这个问题的每个页面一个类元素查询和操作封装成属性与方法用例里只调用语义化的方法不出现任何原始查询表达式。final class FeedListPage { private let app: XCUIApplication init(app: XCUIApplication) { self.app app } private var detailButtons: XCUIElementQuery { app.buttons.matching(identifier: feed_detail) } discardableResult func tapDetail(at index: Int, timeout: TimeInterval 5) - Self { let button detailButtons.element(boundBy: index) XCTAssertTrue(button.waitForExistence(timeout: timeout), 第 \(index) 行的详情按钮未出现) button.tap() return self } }这段代码的价值不在于它多优雅而在于它把怎么找元素和业务要做什么分开了。用例里写feedList.tapDetail(at: 2)读起来就是业务语言。将来 identifier 改名只改页面对象里的那一处。将来定位逻辑要换成基于 label 筛选也只改一处。配合 colibri 这类封装库使用时页面对象内部的实现会更简洁但分层的原则是不变的。我个人的偏好是页面对象只暴露业务动作和状态断言绝不暴露XCUIElement本身。一旦某个用例直接拿到了元素对象去做自定义操作这层抽象就被击穿了后续维护会迅速失控。4.4 手势、输入与截图的封装除了点击UI 测试里常用的还有滑动、长按、拖拽、文本输入这几类操作。它们的共同点是都容易因为时机和坐标问题变得不稳定。滑动尤其典型用固定坐标滑动的代码在不同机型、不同屏幕尺寸上表现完全不同在 iPhone SE 上滑得动的距离到了 iPhone Pro Max 上可能根本不够。更稳的做法是用swipeUp()这类相对手势或者基于元素来滑动比如element.swipeLeft()。如果必须用坐标那就要用归一化坐标0 到 1 的相对值而不是绝对像素值。这一点在写跨设备测试时特别关键很多人本机跑得好好的一上到不同尺寸的模拟器就大面积失败原因就在这里。文本输入还有个隐蔽的坑typeText要求输入框已经获得焦点而这个焦点是需要点击输入框之后才有的。如果输入框还没渲染出来或者被键盘遮挡typeText会静默失败或者把文字输入到错误的地方。稳妥流程是等待输入框出现、点击使其获得焦点、确认键盘已经弹起、再输入文字。截图和附件是另一块容易被忽略的实用功能。给关键步骤或者失败现场附上截图能让排查效率提升一个数量级。我的做法是封装一个辅助方法在断言失败时自动截图并附加到测试报告里命名包含用例名和步骤序号。这样 CI 跑完之后直接看报告里的截图就能判断是界面问题还是定位问题不用去本地复现。5. 稳定性治理与 CI 落地5.1 关键参数与调试开关对照下面这张表是我在多个项目里沉淀下来的配置基线直接抄作业基本不会出大问题具体数值需要根据你的 App 启动速度和 CI 机器性能做微调。配置项本机开发建议值CI 环境建议值说明与取舍理由元素出现等待5 秒8 到 10 秒CI 机器和模拟器启动普遍更慢太短会造成大量假失败用例级超时不限制120 秒有了上限才能避免个别用例卡死拖垮整条流水线重试次数01 次只重试失败用例且要在报告里标记不能掩盖问题并行执行关闭按 CPU 核数开并行能压缩总时长但不同模拟器实例的资源要隔离动画开关关闭关闭系统动画是等待时间的主要来源能关就关失败截图开启开启排查成本最低的一项投入务必保留关于重试我要多说一句。重试是把双刃剑它能让你快速看到排除偶发因素后的真实结果但也会掩盖真实的稳定性问题。我的做法是CI 允许重试一次但同时统计重试率如果某个用例的重试率超过 5%就当成 bug 提单去修而不是让它长期带着重试跑。否则半年之后你会发现整个套件里一半的用例都靠重试才绿那就等于没测。5.2 并行执行与资源隔离测试套件跑得越来越慢之后下一步自然是并行。XCTest 支持把用例分配到多个模拟器实例上同时跑速度提升通常很明显。但它带来的新问题是资源竞争多个实例同时访问同一个测试账号、同一份本地数据库、同一个后端环境很容易互相干扰导致一些在串行时从来没出现过的失败。解决思路有三条一是给每个模拟器实例分配独立的账号和数据空间让它们互不可见二是把有强依赖顺序的用例标记出来强制串行执行三是让后端提供测试专用的环境并支持数据隔离和快速重置。第三条往往需要后端同学配合是最费沟通成本但收益最大的一条。我在实际项目里的经验是如果后端环境不具备隔离能力宁可不并行也不要制造一堆难以复现的随机失败。还有一点常被忽略模拟器的状态。每次跑测试前最好重置模拟器清除上一次运行残留的 App 数据、键盘状态和授权弹窗记录。授权弹窗尤其烦人位置通知、相机权限这些弹窗会盖住界面导致点击落到错误的元素上。处理方式是提前用启动参数注入授权状态或者在测试启动阶段就把弹窗处理掉不要指望它每次都不出现。6. 常见问题速查与排查实录6.1 高频问题对照表现象最可能的原因排查动作元素查询结果为空但界面上明明有元素未开启辅助功能或被父容器吞掉检查 isAccessibilityElement 与容器层级匹配到的元素数量比界面上多列表复用池中的节点被计入打印元素树的调试描述确认节点来源点击报错元素不可点击存在但被遮挡或在可视区域外检查 isHittable必要时先滚动到可见位置本机通过、CI 失败超时太短或环境差异语言、尺寸固定语言与区域放宽超时核对机型第一次跑挂第二次通过启动阶段竞态增加显式等待不要依赖隐式时序输入文字后内容为空输入框未获得焦点先点击输入框确认键盘弹起再输入这张表可以直接贴到团队的 wiki 里当速查卡用。表格里的打印元素树指的是用调试描述接口输出当前界面结构这一步几乎是所有定位问题的起点。很多人在元素找不到时第一反应是改代码其实正确做法是先看一眼元素树里到底有什么往往一眼就能看出问题元素改名了、层级变了、或者出现了预期之外的容器。6.2 几个只有踩过才知道的细节第一个细节不要用 label 做断言的主依据。文案是产品随时会改的东西用文案做断言等于把测试的稳定性绑在了文案评审流程上。能断言的优先级是accessible identifier 最稳其次是关键的 value 或者数量关系最后才是展示文案。如果确实需要断文案把它抽成一个常量集中管理改文案时只改一处。第二个细节等待时间不是越长越好。我曾经为了消灭偶发失败把所有等待都调到 30 秒结果是失败率确实降了但整个套件从 12 分钟涨到了 40 分钟而且真正的问题被彻底掩盖。后来我改成默认 5 秒 对已知慢接口单独设置长超时既保证了速度也保留了问题的可见性。等待时间的本质是一种契约你在告诉团队这个操作在这个时间内应该完成把它随意拉长等于放弃了这份契约的价值。第三个细节测试代码也需要重构和评审。很多团队把 UI 测试当成二等公民代码随便写、没人 review、没人维护最后自然腐烂。我的做法是让测试代码进同一个代码仓库、走同样的 review 流程共用命名规范和格式化工具。这个动作看起来只是流程上的但它对长期维护意愿的影响非常大——没人愿意在一个看起来就很乱的模块里干活。第四个细节别追求 100% 覆盖。UI 自动化适合覆盖关键路径和回归风险高的场景比如登录、下单、支付、设置项的开关状态。把大量细枝末节的 UI 细节都塞进自动化投入产出比会非常难看而且这些用例极不稳定。我通常会把测试金字塔的分配控制在大量单元测试、中等数量的接口测试、少量的 UI 关键路径测试。6.3 关于 colibri 的取舍再补充两句有一点必须坦白这类小型封装库的生态位是尴尬的。它解决的问题真实存在但解决方式并不唯一团队完全可以自己写一层内部封装效果类似还不用引入外部依赖。我选择它的理由主要是省事——现成的东西拿来就用比自研一套再维护要快。但如果你的团队对第三方依赖有严格管控或者这个库的维护活跃度明显下降自己封装一套二十行的扩展方法也是完全合理的选择。我的判断标准是这样的如果这个库能帮我省下至少两天的工作量且能随时移除那就用如果只是把三行代码缩成一行收益不足以抵消依赖成本那就不值得。具体到 colibri我觉得它处在值得用这一侧尤其是团队里新手较多、需要统一的写法约束时一个现成的封装能减少很多风格分歧。最后分享一个我自己一直在用的实践给测试套件建一个稳定性看板。每次 CI 跑完把失败用例、失败原因分类、重试次数、耗时记录下来按周看趋势。如果某个用例连续两周出现在失败榜上就把它钉在当周的技术债清单里。UI 自动化的价值不在于你写了多少条用例而在于这些用例在最需要它绿的时候能不能给你一个可信的答案。这个看板比任何框架选型都更能决定你的自动化建设能不能长期走下去。
第一次在搜索引擎里敲下 colibri跳出来的东西能铺满三屏有人搜到的是嵌入式计算机模块有人搜到的是 iOS UI 自动化测试库还有人搜到的是同名的小众工具和生物信息学脚本。蜂鸟这个词在西班牙语、葡萄牙语里读起来轻快好听于是各路开源作者都爱拿它当项目名结果就是同名撞车撞得七荤八素。我做移动端质量保障这块有些年头了这几年陆续接手的几个 App 项目里UI 自动化从一个写几条冒烟用例意思一下的配角慢慢变成了发版前的硬性关卡。在这个过程中最让我头疼的从来不是写不出用例而是写出来的用例跑十次挂三次。而 colibri 这个库正是我为了解决其中一类具体问题——同一个 accessibility identifier 对应多个元素时的定位与等待——而真正用起来的工具。这篇内容我打算把它掰开揉碎讲清楚它是什么、它补的是哪块短板、怎么接进工程、踩过哪些坑以及怎么把它放到持续集成的流水线里不掉链子。适合已经写过几条 XCUITest、被 flaky 用例折磨过的同学也适合完全没碰过 iOS UI 自动化、想找个切入点的新手。1. 先把这个名字说清楚colibri 到底指哪一摊事1.1 三个同名项目别装错库同名问题必须先解决不然文章看一半你发现我讲的根本不是你搜的那个东西浪费时间。以我的检索经验技术圈里叫 colibri 的东西主要集中在这几个方向一是嵌入式计算模块产品线这类产品通常是核心板形态插在自研载板上跑 Linux 或实时系统做工业控制、医疗设备、车载终端的团队会接触二是 iOS/macOS 平台的 UI 自动化辅助库基于 XCTest 体系做元素查询与操作封装这也是本文的主线三是一些零散的脚本工具、命令行小玩意和学术项目里的数据处理代码生命周期往往很短。判断自己该看哪一篇有个很简单的办法看你的工程里import的是什么。如果打开的是 Xcode 的 UI Testing Target写的是 Swift那你要找的就是第二个如果你面对的是交叉编译工具链、设备树、内核裁减那你该看的是第一个方向的内容。还有一类朋友是纯粹被搜索引擎带偏的本来想搜某款 macOS 上的轻量浏览器或者某个 PDF 阅读器结果落到了开发工具的地盘那直接关掉就行。我之所以强调这个辨析是因为最近两年我至少见过两次团队里有人把硬件模块的文档链接贴进 iOS 项目的技术方案里评审的时候才发现牛头不对马嘴。开源生态里同名不同物是很正常的现象麻烦的是搜索结果会混在一起GitHub 上的仓库也会互相抢占关键词。养成先看语言和依赖再看目录结构的习惯能省下大量试错时间。1.2 为什么 iOS 的 Colibri 值得单独拎出来UI 自动化这个领域从来不缺框架Appium、Maestro、Kaspresso、Detox各路方案各有各的拥趸。但那句话怎么说的越靠近系统底层的方案越稳。XCUITest 是苹果官方提供的能力跑在模拟器和真机上直接和辅助功能Accessibility体系打交道不需要额外的 WebDriver 服务也不需要跨进程通信的中间层。它的确定性是第三方方案很难比的。问题在于官方这套 API 把能力给得很足把顺手给得很吝啬。最典型的例子就是查询元素的链式写法app.tables.cells.matching(identifier: row).element(boundBy: 3)这一长串你得记住查询类型、匹配方式、下标还得自己处理元素还没出现的情况。业务代码里偶尔写一次无所谓当成千上万行测试代码里到处都是这种表达式时可读性和可维护性就开始崩了。colibri 的定位就是在这个缝隙里做事它不去替换 XCTest而是在 XCUITest 之上加一层薄薄的、语义更清晰的封装把常见的查询、等待、点击、输入操作收敛成更短更一致的调用方式尤其针对同 identifier 多元素这类高频场景做了简化。它不是银弹也解决不了被测 App 本身的随机性但它确实能减少一类特定代码噪音让测试代码的意图更直白。我个人的判断是如果你的项目里同一个 identifier 反复出现、测试代码里到处是element(boundBy:)那这个库就有引入价值如果你的页面元素 identifier 管理得很干净、几乎不存在重复那引入它带来的收益会很有限。2. 痛点拆解同 identifier 元素定位为什么这么难2.1 XCUITest 原生的查询模型到底怎么回事要理解 colibri 的价值得先把 XCTest 的查询模型捋清楚。整个体系是围绕元素树构建的App 启动后XCUITest 会通过辅助功能接口把当前界面抓成一棵层级树每个节点有类型Button、Cell、StaticText 等、identifier、label、value 等属性还有它的 frame。查询的本质就是在树上按条件筛选返回一个XCUIElementQuery再从这个 query 里取出具体的XCUIElement去操作。关键的坑在于XCUIElementQuery是一个惰性的、动态求值的对象它不缓存结果。每次你调用element(boundBy: n)它都会重新在当前的树快照上做一次筛选。这意味着两件事一是如果界面还在变化前后两次取到的可能是不同元素二是如果匹配到的元素数量少于你给的下标会直接抛异常或者返回一个永远不存在的元素测试就挂了。再往下说一层exists这个属性也是即时求值——它反映的是你读到它的那一瞬间元素在不在而不是元素会不会在接下来两秒内出现。很多新手写if element.exists { element.tap() }在动画还没结束的时候检查结果当然是 false然后测试静默地跳过了整个操作最后在断言阶段以一句毫无信息量的元素不存在失败。这就是典型的不稳定用例来源。2.2 三种常见错误写法与它们翻车的原因第一种直接下标硬编码。app.buttons.matching(identifier: item).element(boundBy: 0).tap()。看起来没问题但列表第一项的顺序可能因为服务端返回顺序变化、本地缓存差异、甚至排序规则的微调而改变。你依赖的是位置而位置在动态列表里是最不可靠的信息。第二种用firstMatch图省事。app.buttons[item].firstMatch在只有唯一元素时确实快因为它一旦找到第一个匹配就停止搜索性能上有优势。但如果页面上有三个同名按钮firstMatch选中的是树里最先被遍历到的那个未必是你视觉上认为的第一个也未必是用户会点的那个。这个坑特别隐蔽因为大部分时候它看起来是对的。第三种混淆identifier和label。app.buttons[xxx]这个下标写法实际上是按 identifier 优先、label 兜底去匹配的。当某天设计师把按钮文案从确定改成确认你的用例就全线飘红而你根本没动过测试代码。正确的做法是给所有需要交互的元素显式配置 accessibility identifier用稳定的人工编号而不是自然语言文案。这三种写法我在不同的项目里都见过而且往往是混着来的。你会发现问题都不在于写不出来而在于写出来的东西对上下文过于敏感。UI 测试的稳定性本质上是在和不确定性作斗争网络、动画、异步渲染、列表复用每一个都在制造不确定性。代码写得越贴近我确定要操作哪一个元素就越稳。2.3 Colibri 的封装思路与取舍理解了上面的痛点colibri 的取舍就很清楚了。它没有去发明一套新的元素描述语言也没有搞出跨平台抽象层而是做了三件事把冗长的 query 链式调用收敛成更短的入口把等待元素出现/消失和后续操作合并成一步避免忘记等待对重复 identifier 场景提供按顺序或按可见性选择元素的辅助方法。这种薄封装的路线有利有弊。好处是学习成本极低你原来会写 XCUITest看半小时就能上手出问题时也能直接退回原生 API 排查不存在黑盒。坏处是它不解决语义层面的问题——如果页面上五个元素的 identifier 全都叫cell库也猜不出你想点哪个仍然需要你给出下标或者别的筛选条件。指望引入一个库就让 flaky 测试变成零失败这个预期要先放下来。我在选型时有个习惯优先考虑能不能随时甩掉的工具。如果一个封装库突然停止维护或者某个版本引入了不兼容变更我能不能在半天内把项目切回原生写法colibri 这类薄封装的答案是能这也是我愿意在正式项目里用它的原因之一。反过来那些深度侵入业务代码、要求你按它的方式重构整个工程结构的框架我会更谨慎。3. 从零搭一个能跑的最小工程3.1 依赖接入与版本选择colibri 是一个纯 Swift 的库走 Swift Package Manager 接入是最省事的方式。具体操作是在 Xcode 里选中你的 UI Testing Target注意是测试 Target 而不是主 App Target然后在 Package Dependencies 里添加仓库地址地址以仓库首页为准这类小库偶尔会迁移。依赖规则建议用Up to Next Major Version因为这类封装库的 API 面不大大版本升级通常意味着方法签名有调整锁死小版本反而会错过修复。如果你所在的项目还在用 CocoaPods 统一管理依赖也可以走 pod 方式但要注意 UI 测试 Target 在 Podfile 里的 target 声明必须写对很多人踩过的坑是把依赖加到了主 App 上结果编译通过了但测试代码里import不到排查半天。判断方法很简单打开 Build Settings 里的 Framework Search Paths看依赖产物是不是挂在测试 Target 下面。接入之后建议先做一次空跑验证新建一个测试方法方法体里只放一句XCTAssertTrue(true)直接跑一次。这一步的目的是确认 Target 配置、签名、模拟器选择都没问题把环境问题和代码问题分开。我见过太多人一上来就写几十行用例失败了分不清是库没接好还是逻辑写错了白白浪费一下午。这个先跑通空壳的习惯是我做自动化的第一原则。3.2 示例工程与测试 Target 的配置要点为了让示例可复现我们先假定被测界面是一个列表页里面有若干个结构相同的行每行有一个标题文本、一个开关、一个进入详情的按钮。这个结构非常典型电商、资讯、设置页都是这个套路。三个元素的 accessibility identifier 分别设为feed_title、feed_switch、feed_detail也就是每一行都会重复出现这三个 identifier。这正是 colibri 的主场。在给元素配 identifier 之前有个前提条件必须确认这个元素是可访问的。如果一个自定义视图没有开启 isAccessibilityElement或者被上层容器吞掉了辅助功能信息那么无论你怎么配 identifierXCUITest 都看不到它。表现是查询结果永远是空的而且不会报错只是匹配不到。解决办法是在自定义控件的初始化里设置isAccessibilityElement true并给它一个合适的 accessibilityTraits让系统知道它是按钮还是文本。另外如果你的列表是 UITableView 或 UICollectionView单元格复用会让元素树里的节点顺序和出现时机变得微妙。同一个 identifier 在屏幕上可能对应多个可访问节点而不可见的复用池里的节点有时也会被算进去。这是很多明明只有三行为什么匹配到五个这类诡异现象的根源。后面讲排查技巧时我会给出定位方法。测试 Target 层面还要注意语言和区域设置。如果你的 App 做了多语言测试运行时的系统语言会影响 label 内容从而影响按 label 的匹配结果。稳妥做法是给测试 Target 设置固定的-AppleLanguages和-AppleLocale启动参数让每次运行的环境完全一致。这个设置不写本地跑通、CI 上挂掉是常有的事。3.3 第一条测试用例环境就绪后第一条用例我建议选最有代表性的点击列表第三行的详情按钮。代码大概长这样方法名以仓库最新文档为准思路是通用的import XCTest final class FeedListUITests: XCTestCase { private var app: XCUIApplication! override func setUpWithError() throws { continueAfterFailure false app XCUIApplication() app.launchArguments [-AppleLanguages, (zh-Hans), -AppleLocale, zh_CN] app.launch() } func testTapThirdRowDetail() throws { let detailButton app.buttons .matching(identifier: feed_detail) .element(boundBy: 2) XCTAssertTrue(detailButton.waitForExistence(timeout: 5), 第三行的详情按钮在 5 秒内没有出现) detailButton.tap() XCTAssertTrue(app.staticTexts[detail_title].waitForExistence(timeout: 5), 详情页标题没有加载出来) } }这几行代码里有三个值得说的细节。第一continueAfterFailure false要放在最早的位置它保证一条用例失败后立即停止避免后续操作在一堆报错上继续执行把真正的错误信息淹没。第二waitForExistence是必须的不能直接 tap因为 App 启动到列表渲染完成有时间差。第三失败时给的提示信息要写清楚是哪一行的哪个按钮因为将来定位问题时控制台里那句提示就是你唯一的线索。4. 核心能力逐项拆解4.1 查询与索引定位回到重复 identifier 的问题colibri 提供的价值在于把匹配 取下标这段逻辑变得更短、更统一。原生写法是matching(identifier:)加element(boundBy:)封装之后通常是一个链式方法就能取到目标元素可读性提升明显。但我要强调的是无论用哪种写法下标从哪来这个问题依然要你自己回答。下标取值有三条判断依据。第一条是屏幕上的视觉顺序这需要你确认元素树的遍历顺序和视觉顺序一致大多数纵向列表是一致的但遇到横向滚动或者复杂的嵌套容器就不一定。第二条是业务语义顺序比如取第一个未读的消息这种就不该用下标而应该通过元素的其他属性value、label 或者自定义标识来筛选。第三种是唯一标识理想情况下每行的 identifier 都带上业务 id比如feed_detail_1024这样完全不需要下标。我的建议是能做成唯一标识的一律做唯一标识实在做不了的比如纯位置相关的交互再用下标并且把下标定义为命名常量附上注释说明它对应哪个业务对象。这条规则看起来啰嗦但在项目进行到第三个月、业务方改了三版需求之后你会感谢当时写了注释的自己。4.2 等待、重试与超时分层UI 自动化里 90% 的随机失败都和时机有关。元素还没渲染完就操作、动画还没结束就断言、页面切换过程中查询了旧页面这些都会导致失败而且失败得毫无规律。解决思路是分层的不能一个固定 sleep 走天下。第一层是隐式等待也就是waitForExistence这类。它内部是轮询机制每隔一小段时间重新查询一次直到元素出现或者超时。这个超时值不要设得太短timeout: 1在 CI 机器上几乎等于碰运气也不要设得太长太长会让失败反馈延迟整体耗时长到没人愿意跑。我的经验值是本机开发时 5 秒起步CI 上乘 1.5 到 2 倍。第二层是操作前的状态确认。要点击的元素不仅需要存在还需要isHittable。存在但不可点击的情况太常见了元素被键盘遮挡、在滚动区域之外、被一个透明的遮罩层盖住。只判断exists就点击系统会尝试滚动或者直接报错这个行为在不同 iOS 版本上还有差异。稳妥做法是组合判断或者用封装库里更完整的可用性检查方法。第三层是整体超时。XCTest 有单个用例的超时上限超过就会被判定为超时失败。这个值在 CI 上建议放宽因为 CI 机器性能和模拟器启动速度都不稳定。同时要注意如果某个用例长期处于接近超时边缘它是潜在的不稳定点即使现在没挂也迟早会挂。定期统计每个用例的耗时分布把明显偏慢的那些挑出来优化是保持测试套件健康的有效手段。4.3 页面对象模式的落地姿势测试代码规模一旦上去最大的敌人就是重复。同一个元素在十个用例里被以相同的方式查询某天界面改了你要改十个地方。页面对象模式Page Object就是来解决这个问题的每个页面一个类元素查询和操作封装成属性与方法用例里只调用语义化的方法不出现任何原始查询表达式。final class FeedListPage { private let app: XCUIApplication init(app: XCUIApplication) { self.app app } private var detailButtons: XCUIElementQuery { app.buttons.matching(identifier: feed_detail) } discardableResult func tapDetail(at index: Int, timeout: TimeInterval 5) - Self { let button detailButtons.element(boundBy: index) XCTAssertTrue(button.waitForExistence(timeout: timeout), 第 \(index) 行的详情按钮未出现) button.tap() return self } }这段代码的价值不在于它多优雅而在于它把怎么找元素和业务要做什么分开了。用例里写feedList.tapDetail(at: 2)读起来就是业务语言。将来 identifier 改名只改页面对象里的那一处。将来定位逻辑要换成基于 label 筛选也只改一处。配合 colibri 这类封装库使用时页面对象内部的实现会更简洁但分层的原则是不变的。我个人的偏好是页面对象只暴露业务动作和状态断言绝不暴露XCUIElement本身。一旦某个用例直接拿到了元素对象去做自定义操作这层抽象就被击穿了后续维护会迅速失控。4.4 手势、输入与截图的封装除了点击UI 测试里常用的还有滑动、长按、拖拽、文本输入这几类操作。它们的共同点是都容易因为时机和坐标问题变得不稳定。滑动尤其典型用固定坐标滑动的代码在不同机型、不同屏幕尺寸上表现完全不同在 iPhone SE 上滑得动的距离到了 iPhone Pro Max 上可能根本不够。更稳的做法是用swipeUp()这类相对手势或者基于元素来滑动比如element.swipeLeft()。如果必须用坐标那就要用归一化坐标0 到 1 的相对值而不是绝对像素值。这一点在写跨设备测试时特别关键很多人本机跑得好好的一上到不同尺寸的模拟器就大面积失败原因就在这里。文本输入还有个隐蔽的坑typeText要求输入框已经获得焦点而这个焦点是需要点击输入框之后才有的。如果输入框还没渲染出来或者被键盘遮挡typeText会静默失败或者把文字输入到错误的地方。稳妥流程是等待输入框出现、点击使其获得焦点、确认键盘已经弹起、再输入文字。截图和附件是另一块容易被忽略的实用功能。给关键步骤或者失败现场附上截图能让排查效率提升一个数量级。我的做法是封装一个辅助方法在断言失败时自动截图并附加到测试报告里命名包含用例名和步骤序号。这样 CI 跑完之后直接看报告里的截图就能判断是界面问题还是定位问题不用去本地复现。5. 稳定性治理与 CI 落地5.1 关键参数与调试开关对照下面这张表是我在多个项目里沉淀下来的配置基线直接抄作业基本不会出大问题具体数值需要根据你的 App 启动速度和 CI 机器性能做微调。配置项本机开发建议值CI 环境建议值说明与取舍理由元素出现等待5 秒8 到 10 秒CI 机器和模拟器启动普遍更慢太短会造成大量假失败用例级超时不限制120 秒有了上限才能避免个别用例卡死拖垮整条流水线重试次数01 次只重试失败用例且要在报告里标记不能掩盖问题并行执行关闭按 CPU 核数开并行能压缩总时长但不同模拟器实例的资源要隔离动画开关关闭关闭系统动画是等待时间的主要来源能关就关失败截图开启开启排查成本最低的一项投入务必保留关于重试我要多说一句。重试是把双刃剑它能让你快速看到排除偶发因素后的真实结果但也会掩盖真实的稳定性问题。我的做法是CI 允许重试一次但同时统计重试率如果某个用例的重试率超过 5%就当成 bug 提单去修而不是让它长期带着重试跑。否则半年之后你会发现整个套件里一半的用例都靠重试才绿那就等于没测。5.2 并行执行与资源隔离测试套件跑得越来越慢之后下一步自然是并行。XCTest 支持把用例分配到多个模拟器实例上同时跑速度提升通常很明显。但它带来的新问题是资源竞争多个实例同时访问同一个测试账号、同一份本地数据库、同一个后端环境很容易互相干扰导致一些在串行时从来没出现过的失败。解决思路有三条一是给每个模拟器实例分配独立的账号和数据空间让它们互不可见二是把有强依赖顺序的用例标记出来强制串行执行三是让后端提供测试专用的环境并支持数据隔离和快速重置。第三条往往需要后端同学配合是最费沟通成本但收益最大的一条。我在实际项目里的经验是如果后端环境不具备隔离能力宁可不并行也不要制造一堆难以复现的随机失败。还有一点常被忽略模拟器的状态。每次跑测试前最好重置模拟器清除上一次运行残留的 App 数据、键盘状态和授权弹窗记录。授权弹窗尤其烦人位置通知、相机权限这些弹窗会盖住界面导致点击落到错误的元素上。处理方式是提前用启动参数注入授权状态或者在测试启动阶段就把弹窗处理掉不要指望它每次都不出现。6. 常见问题速查与排查实录6.1 高频问题对照表现象最可能的原因排查动作元素查询结果为空但界面上明明有元素未开启辅助功能或被父容器吞掉检查 isAccessibilityElement 与容器层级匹配到的元素数量比界面上多列表复用池中的节点被计入打印元素树的调试描述确认节点来源点击报错元素不可点击存在但被遮挡或在可视区域外检查 isHittable必要时先滚动到可见位置本机通过、CI 失败超时太短或环境差异语言、尺寸固定语言与区域放宽超时核对机型第一次跑挂第二次通过启动阶段竞态增加显式等待不要依赖隐式时序输入文字后内容为空输入框未获得焦点先点击输入框确认键盘弹起再输入这张表可以直接贴到团队的 wiki 里当速查卡用。表格里的打印元素树指的是用调试描述接口输出当前界面结构这一步几乎是所有定位问题的起点。很多人在元素找不到时第一反应是改代码其实正确做法是先看一眼元素树里到底有什么往往一眼就能看出问题元素改名了、层级变了、或者出现了预期之外的容器。6.2 几个只有踩过才知道的细节第一个细节不要用 label 做断言的主依据。文案是产品随时会改的东西用文案做断言等于把测试的稳定性绑在了文案评审流程上。能断言的优先级是accessible identifier 最稳其次是关键的 value 或者数量关系最后才是展示文案。如果确实需要断文案把它抽成一个常量集中管理改文案时只改一处。第二个细节等待时间不是越长越好。我曾经为了消灭偶发失败把所有等待都调到 30 秒结果是失败率确实降了但整个套件从 12 分钟涨到了 40 分钟而且真正的问题被彻底掩盖。后来我改成默认 5 秒 对已知慢接口单独设置长超时既保证了速度也保留了问题的可见性。等待时间的本质是一种契约你在告诉团队这个操作在这个时间内应该完成把它随意拉长等于放弃了这份契约的价值。第三个细节测试代码也需要重构和评审。很多团队把 UI 测试当成二等公民代码随便写、没人 review、没人维护最后自然腐烂。我的做法是让测试代码进同一个代码仓库、走同样的 review 流程共用命名规范和格式化工具。这个动作看起来只是流程上的但它对长期维护意愿的影响非常大——没人愿意在一个看起来就很乱的模块里干活。第四个细节别追求 100% 覆盖。UI 自动化适合覆盖关键路径和回归风险高的场景比如登录、下单、支付、设置项的开关状态。把大量细枝末节的 UI 细节都塞进自动化投入产出比会非常难看而且这些用例极不稳定。我通常会把测试金字塔的分配控制在大量单元测试、中等数量的接口测试、少量的 UI 关键路径测试。6.3 关于 colibri 的取舍再补充两句有一点必须坦白这类小型封装库的生态位是尴尬的。它解决的问题真实存在但解决方式并不唯一团队完全可以自己写一层内部封装效果类似还不用引入外部依赖。我选择它的理由主要是省事——现成的东西拿来就用比自研一套再维护要快。但如果你的团队对第三方依赖有严格管控或者这个库的维护活跃度明显下降自己封装一套二十行的扩展方法也是完全合理的选择。我的判断标准是这样的如果这个库能帮我省下至少两天的工作量且能随时移除那就用如果只是把三行代码缩成一行收益不足以抵消依赖成本那就不值得。具体到 colibri我觉得它处在值得用这一侧尤其是团队里新手较多、需要统一的写法约束时一个现成的封装能减少很多风格分歧。最后分享一个我自己一直在用的实践给测试套件建一个稳定性看板。每次 CI 跑完把失败用例、失败原因分类、重试次数、耗时记录下来按周看趋势。如果某个用例连续两周出现在失败榜上就把它钉在当周的技术债清单里。UI 自动化的价值不在于你写了多少条用例而在于这些用例在最需要它绿的时候能不能给你一个可信的答案。这个看板比任何框架选型都更能决定你的自动化建设能不能长期走下去。
