1. 项目概述：为什么选择Calabash-iOS？

在移动应用开发，尤其是iOS开发领域，测试自动化一直是个让人又爱又恨的话题。爱的是它能解放重复劳动，恨的是iOS生态的封闭性让很多自动化工具水土不服，要么学习曲线陡峭，要么维护成本高昂。我经历过从纯手工测试，到尝试各种UI自动化框架，再到最终将Calabash-iOS作为核心自动化体系落地的完整周期。今天，我就来聊聊如何从零开始，用Calabash-iOS搭建一个真正能用、好用的iOS自动化测试体系。

Calabash-iOS是什么？简单说，它是一个让你能用自然语言（Cucumber的Gherkin语法）来编写iOS应用UI自动化测试脚本的开源框架。它的核心价值在于“跨角色协作”：产品经理、测试工程师甚至是不太懂代码的业务人员，都能看懂用Gherkin写的测试场景（Feature文件），而开发者则负责用Ruby去实现这些场景背后的具体步骤（Step Definitions）。这种“行为驱动开发”（BDD）的模式，让自动化测试不再是开发团队的黑盒，而是连接需求、开发与验证的桥梁。

为什么是它，而不是其他工具？在iOS自动化领域，你有XCTest/XCUITest（苹果亲儿子）、Appium（跨平台明星）、EarlGrey（Google出品）等选择。Calabash-iOS的优势在于其独特的定位：对非技术角色极其友好，且对应用代码的侵入性极低。你不需要为了自动化而大量修改你的Swift或Objective-C源码，它通过注入一个测试服务器（Calabash Server）到你的应用包中来实现与应用UI的交互。这意味着，你可以对线上版本的应用包（.ipa）直接进行自动化测试，这在某些需要验证已发布应用功能的场景下非常有用。当然，它也有缺点，比如执行速度可能不如原生XCUITest，环境搭建稍显繁琐。但对于追求测试用例可读性、团队协作效率以及测试资产长期可维护性的团队来说，这些投入是值得的。

2. 环境搭建与项目初始化：避开第一个坑

万事开头难，Calabash-iOS的初始环境搭建是第一个拦路虎。很多新手在这里就被劝退了，其实只要理清脉络，一步步来，并不复杂。

2.1 核心工具链安装

Calabash-iOS的运行依赖于Ruby环境。macOS自带的Ruby版本通常比较旧，且系统级目录权限管理严格，直接使用容易出问题。因此，我强烈建议使用rbenv或rvm这类Ruby版本管理工具来创建一个独立、干净的Ruby环境。

首先，如果你没有Homebrew，先安装它（这是macOS包管理器，后续安装依赖会方便很多）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

接着，安装rbenv和ruby-build：

brew install rbenv ruby-build echo 'eval "$(rbenv init -)"' >> ~/.zshrc # 如果你用的是zsh，bash用户则添加到~/.bash_profile source ~/.zshrc

然后，安装一个较新版本的Ruby，Calabash-iOS目前对Ruby 2.7.x 或 3.x 版本支持较好：

rbenv install 3.1.2 rbenv global 3.1.2

安装完成后，验证一下：

ruby -v

接下来，安装Calabash-iOS的核心gem包。这里有个关键点：不要直接gem install calabash-cucumber。因为Calabash-iOS框架包含客户端（Ruby库）和服务器端（注入到App中的部分），为了版本匹配，最好使用其提供的安装器。

gem install calabash-cucumber

安装完gem后，我们还需要xcode-select命令行工具，确保其指向正确的Xcode版本：

xcode-select -p # 查看当前路径 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer # 如果路径不对，进行设置

2.2 为你的iOS项目集成Calabash

假设你有一个现成的Xcode项目（假设叫MyAwesomeApp），你需要将Calabash集成进去。Calabash官方推荐使用calabash-ios setup命令来初始化。

首先，cd到你的iOS项目根目录（即包含.xcodeproj或.xcworkspace文件的目录）。 然后执行：

calabash-ios setup

这个命令会做几件事：

1. 在你的项目目录下创建一个名为features的文件夹，这是存放所有Cucumber测试用例（.feature文件）和步骤定义（.rb文件）的地方。
2. 可能会提示你选择对应的.xcodeproj文件。
3. 它会在你的Xcode项目中，自动创建一个新的-calScheme（例如MyAwesomeApp-cal）。这个Scheme是专门用于Calabash测试的，它会在构建时自动将Calabash服务器（一个静态库）链接到你的应用中。

注意：calabash-ios setup命令在较新版本中可能行为有变化。如果它没有自动创建-calScheme，你可能需要手动操作：复制一份你原有的App Scheme，在新Scheme的Build Settings中，找到Other Linker Flags，添加-force_load "$(DEVICE_RUNTIME)/Developer/Library/PrivateFrameworks/Calabash.framework/Calabash"（具体路径请参考Calabash官方文档）。同时，在Build Phases中添加一个新的Run Script Phase，脚本内容为"${CALABASH_PATH}/run"。这个过程比较繁琐，也是初期的主要难点之一。如果自动创建失败，建议查阅对应版本的Calabash-iOS官方Wiki。

执行成功后，你的项目结构会多出一个features目录，里面已经有了一些示例文件。此时，你可以尝试用-calScheme编译你的应用，目标选择iOS Simulator。如果编译成功，那么最艰难的一步就过去了。

3. 编写你的第一个可读性测试用例

环境搭好，我们来点实际的。Calabash的核心魅力在于用Gherkin语法编写测试用例。它读起来就像一份产品需求文档。

在features目录下，创建一个新的文件，例如login.feature。内容如下：

功能：用户登录 为了确保用户能安全访问个人账户 作为一个应用用户 我希望能够使用正确的凭据登录系统 场景大纲：使用有效和无效凭据登录 假如我打开了应用 当我在“用户名”输入框中输入“<用户名>” 并且我在“密码”输入框中输入“<密码>” 并且我点击“登录”按钮 那么我应该看到“<预期结果>”文本 例子： | 用户名 | 密码 | 预期结果 | | alice | 123456 | 欢迎回来，alice！ | | bob | wrongpw | 用户名或密码错误 |

这段代码描述了两个测试场景：一个用正确密码登录成功，一个用错误密码登录失败。即使不懂编程的同事，也能一眼看懂测试意图。这就是BDD带来的沟通效率提升。

但光有描述不行，还需要告诉Calabash如何执行“在‘用户名’输入框中输入”这样的动作。这就是步骤定义（Step Definitions）的工作。在features/step_definitions目录下，创建一个login_steps.rb文件。

假如(/^我打开了应用$/) do # Calabash会自动启动应用，这一步通常可以为空，或者做一些初始状态重置 # 例如：calabash_reset end 当(/^我在“([^”]*)”输入框中输入“([^”]*)”$/) do |field_name, text| # 核心：如何定位元素？Calabash提供了多种查询方式 # 方式1：通过 accessibilityLabel (推荐，需开发配合) touch("view marked:'#{field_name}'") wait_for_keyboard keyboard_enter_text text # 方式2：通过视图类型和序号（脆弱，不推荐） # touch("UITextField index:0") # 方式3：通过部分文本（如果输入框有placeholder） # touch("textField placeholder:'#{field_name}'") # wait_for_keyboard # keyboard_enter_text text end 当(/^我点击“([^”]*)”按钮$/) do |button_name| touch("button marked:'#{button_name}'") end 那么(/^我应该看到“([^”]*)”文本$/) do |expected_text| # 等待并断言屏幕上出现了指定文本 wait_for_element_exists("* text:'#{expected_text}'") # 更严格的断言：检查该文本是否可见 # fail unless element_exists("* text:'#{expected_text}'") end

这里涉及了Calabash最核心的概念之一：元素查询。touch("view marked:'#{field_name}'")这行代码的意思是，触摸（点击）一个accessibilityLabel属性等于field_name变量的视图。accessibilityLabel是iOS为辅助功能（如VoiceOver）提供的属性，Calabash极大地利用了这套机制来定位元素。这意味着，为了让自动化测试更稳定，你需要推动开发同学为关键UI元素设置合理且唯一的accessibilityLabel。这是成功实施Calabash的关键前提，也是团队协作的体现。

4. 核心技能：元素定位、等待与断言

编写稳定可靠的自动化测试，90%的工作在于如何处理元素定位和异步等待。这是从“脚本能跑”到“脚本可靠”的必经之路。

4.1 元素定位策略详解

Calabash提供了丰富的查询API，定位元素主要靠query方法或其简写形式（如touch(“query”)）。查询语句类似于CSS选择器。

1. 通过accessibilityLabel（首选）：这是最稳定、最推荐的方式。要求开发在代码中设置。

   # Swift示例：一个登录按钮 loginButton.accessibilityLabel = “登录按钮” # Calabash查询 touch(“button marked:‘登录按钮’”)

   对于自定义视图，可能需要重写accessibilityLabel的getter方法。

2. 通过文本内容：适用于UILabel、UIButton等有text属性的控件。

   touch(“button text:‘确定’”) # 点击文字为“确定”的按钮 wait_for_element_exists(“label text:‘加载成功…’”) # 等待某个文本出现

   注意：如果应用支持多语言，直接使用UI文本定位会使测试脚本与语言绑定，不利于维护。可以考虑使用accessibilityIdentifier（它专为自动化测试设计，不会随语言改变）或者将文本内容提取到配置文件中。

3. 通过视图类型和索引：万不得已时使用，稳定性最差。

   query(“UITextField”) # 找到所有UITextField touch(“UITextField index:1”) # 点击第二个UITextField

   一旦UI布局顺序发生变化，测试就会失败。

4. 通过父视图与子视图关系：处理复杂布局。

   # 找到第一个UITableView，然后找到它的第0行第0个单元格里的UILabel cell_label = query(“tableView index:0 tableViewCell index:0 label”) puts cell_label.first[“text”] # 输出该label的文本

实操心得：在项目初期，就和开发团队约定一套accessibilityLabel的命名规范（例如，使用页面名_组件类型_用途的格式：login_username_textfield）。并考虑将这部分检查纳入代码审查流程，从源头保障自动化测试的可行性。

4.2 智能等待：告别sleep

在UI自动化中，硬编码的sleep是万恶之源，它拖慢执行速度且不可靠。Calabash提供了强大的等待机制。

• wait_for系列：这是你最常用的工具。

  # 等待某个元素出现，最多等10秒 wait_for_element_exists(“* marked:‘成功提示’”, timeout: 10) # 等待某个元素消失（比如加载动画） wait_for_element_does_not_exist(“* marked:‘加载中’”, timeout: 15) # 等待一个条件成立 wait_for(timeout: 10) { query(“*”, :isAnimating).first == 0 } # 等待所有动画结束

• touch、pan等操作本身也内置了等待。它们会先尝试执行，如果目标元素不存在，会等待一小段时间（可配置）再次尝试，超过重试次数才失败。

• 处理键盘：输入文本前，确保键盘已弹出。

  touch(“textField marked:‘搜索框’”) wait_for_keyboard # 等待键盘动画完成 keyboard_enter_text(“要搜索的关键词”) # 完成后，如果需要关闭键盘 tap_keyboard_action_key # 点击键盘上的回车等动作键 # 或者 hide_soft_keyboard # 尝试隐藏键盘（模拟点击键盘外区域）

4.3 断言与验证

测试的核心是验证。除了上面用到的wait_for_element_exists（它本身也带有断言性质，失败会抛异常），Calabash还可以与RSpec等断言库结合，但通常其内置方法已足够。

那么(/^“我的账户”页面应该显示用户名“(.+)”$/) do |username| # 方法1：使用wait_for，失败会抛出明确的错误信息 wait_for_element_exists(“label marked:‘display_name’ text:‘#{username}’”) # 方法2：使用query获取值后手动断言 actual_name = query(“label marked:‘display_name’”, :text).first unless actual_name == username raise “期望用户名为 #{username}，但实际是 #{actual_name}” end # 方法3：检查元素属性 is_enabled = query(“button marked:‘提交’”, :isEnabled).first fail “提交按钮应该是可点击状态” if is_enabled == 0 end

断言不仅要验证“是什么”，还要在失败时提供清晰的错误信息，方便快速定位问题。

5. 构建完整的自动化测试体系

单个测试用例跑通只是起点，我们的目标是建立一个可持续集成、可维护的自动化测试体系。这涉及到测试数据管理、测试组织、持续集成和报告生成。

5.1 测试数据管理与场景组织

• 使用Background：对于多个场景都需要执行的公共步骤，比如每次测试前先注销、清理数据，可以写在Background里。

  功能：商品管理 Background: 假如我已以管理员身份登录 并且我导航到“商品管理”页面

• 数据驱动测试：正如前面场景大纲的例子所示，用例子表格来驱动测试，是覆盖多种输入组合的高效方式。可以将测试数据提取到独立的.yml或.json文件中，在步骤定义中读取。
• Tags标签：使用@smoke、@regression、@wip等标签来分类测试用例。运行时可以只执行特定标签的测试。

  cucumber --tags @smoke # 只执行冒烟测试 cucumber --tags “not @wip” # 执行除了“工作中”以外的所有测试

5.2 集成到CI/CD流水线

自动化测试只有集成到持续集成（CI）系统中，才能发挥最大价值。我们可以在Jenkins、GitLab CI、GitHub Actions等平台上运行Calabash测试。

核心步骤通常包括：

1. 选择节点/代理：确保CI机器是macOS，并安装了所需版本的Xcode、Ruby以及项目依赖。
2. 代码拉取与依赖安装：拉取最新代码，执行bundle install（如果你用Gemfile管理Ruby依赖）安装calabash-cucumber等gem。
3. 构建测试包：使用xcodebuild命令，用-calScheme构建用于模拟器或真机的.app文件。

   xcodebuild -workspace MyAwesomeApp.xcworkspace -scheme MyAwesomeApp-cal -configuration Debug -destination ‘platform=iOS Simulator,name=iPhone 14,OS=latest’ -derivedDataPath build

4. 启动模拟器并执行测试：启动一个干净的模拟器，安装.app，然后运行cucumber。

   # 启动模拟器（可以提前用instruments -s devices查看可用设备） xcrun simctl boot “iPhone 14” # 运行测试 APP_BUNDLE_PATH=“./build/Build/Products/Debug-iphonesimulator/MyAwesomeApp-cal.app” cucumber

5. 生成测试报告：Cucumber支持多种格式的报告，如html、json。集成到CI中，可以生成美观的报告并归档。

   cucumber --format html --out reports/report.html --format pretty

避坑指南：CI环境下的模拟器管理是个大坑。务必在测试开始前，重置模拟器状态（xcrun simctl erase all），确保每次测试都在干净的环境中进行。另外，模拟器的启动和安装应用需要时间，在脚本中要加入足够的等待或重试逻辑。

5.3 测试报告与失败分析

清晰的测试报告是快速排查问题的关键。除了Cucumber自带的报告，可以结合screen_shooter等gem，在测试失败时自动截屏。

# 在features/support/env.rb中配置 require ‘screen_shooter’ # 在测试失败后自动截图 After do |scenario| if scenario.failed? Screenshot.screenshot_and_save_page end end

这些截图和错误堆栈信息，能极大帮助开发重现和修复问题。可以将失败截图作为附件，连同测试报告一起通过CI系统通知给相关人员。

6. 高级技巧与实战避坑

掌握了基础，再来看看那些能让你的自动化脚本更健壮、更高效的高级技巧和常见坑点。

6.1 处理网络请求与状态模拟

UI测试不应该依赖不稳定的后端服务。我们可以利用一些技术来模拟网络状态或拦截请求。

• 使用启动参数/环境变量：在启动App时，通过Calabash传递参数，让App切换到“测试模式”，连接到一个Mock服务器或使用本地桩数据。

  # 在Cucumber的Before hook中 Before do @app = Calabash::Cucumber::Launcher.new launch_options = { # 传递一个自定义的启动参数给App :args => [“-TEST_MODE”, “YES”, “-MOCK_API_BASE”, “http://localhost:8080”] } @app.relaunch(launch_options) end

  在App的AppDelegate中，你可以读取这些启动参数来配置网络层。

• 使用OHHTTPStubs等库（需代码配合）：如果你的App代码中集成了网络拦截库（如OHHTTPStubs），你甚至可以在测试脚本中动态地注册和移除HTTP桩，实现更精细的控制。但这需要开发端的支持。

6.2 测试跨应用交互与系统控件

测试分享到微信、调用系统相册等场景，涉及与应用外的交互。Calabash本身主要针对单个应用内测试。对于系统控件，可以尝试以下方法：

1. 通过accessibilityLabel定位：iOS的系统控件（如UIActivityViewController中的分享选项）有时也有可访问性标识。你可以尝试用query(“all”)打印出当前所有视图信息，寻找可用的标识。
2. 使用坐标点击（最后手段）：如果实在无法通过标识定位，且UI位置相对固定，可以考虑使用tap_coordinate({x: 100, y: 200})。但这种方法极其脆弱，屏幕尺寸、系统版本一变就可能失效，应尽量避免。
3. 单元测试与集成测试分离：对于这类强依赖外部不可控环境的复杂交互，可以考虑将其拆解。用单元测试验证分享逻辑的构建是否正确，用集成测试验证核心业务流程，而将“点击系统分享按钮”这类操作视为已知前提或通过手动测试覆盖。

6.3 性能与稳定性调优

当测试用例成百上千时，执行速度和稳定性成为瓶颈。

• 重用模拟器/设备：不要每条测试都重启模拟器，这非常耗时。可以在整个测试套件开始前启动并安装应用，每条测试场景前后只重置应用状态（使用Calabash的calabash_reset方法或backdoor机制调用App内的重置方法）。
• 并行测试：如果CI资源充足，可以将测试套件按模块或标签拆分，在多台机器或同一个机器的多个模拟器实例上并行运行。这需要更复杂的CI脚本编排。
• 优化查询：避免使用query(“*”)这样宽泛的查询，尽量使用更精确的定位方式。低效的查询会拖慢执行速度。
• 合理使用标签：为那些不稳定、耗时长或依赖外部环境的测试加上@flaky、@slow、@external标签，在常规CI流水线中排除它们，定期单独运行。

6.4 常见问题排查实录

1. 错误：Calabash::Cucumber::WaitHelpers::WaitError: Timed out waiting for…

   • 原因：最常见。元素超时未出现。
   • 排查：
     • 首先，用query(“all”)或print_views（来自calabash-cucumber/calabash_steps）打印当前页面所有视图，确认元素是否存在，以及它的accessibilityLabel或text是否正确。
     • 检查是否有动画、网络请求未完成。增加timeout时间，或在操作前增加明确的等待条件。
     • 检查是否在正确的页面。可能上一步操作（如点击）未生效，导航失败。
     • 对于UITableView或UICollectionView中的元素，确保它已经滚动到屏幕上。可以先使用scroll方法。

2. 错误：Unable to find any element…或Query returned no results

   • 原因：查询语句找不到任何匹配元素。
   • 排查：检查查询语句拼写是否正确，属性名是否匹配。特别注意，marked对应的是accessibilityLabel，而不是accessibilityIdentifier（对应id）。使用query(“view accessibilityLabel:‘xxx’”)和query(“view accessibilityIdentifier:‘xxx’”)来区分。

3. 应用在测试中崩溃

   • 原因：可能是Calabash服务器与App版本不兼容，或者是App代码中存在仅在测试环境下触发的bug。
   • 排查：
     • 查看设备日志（Console.app 或xcrun simctl logverbose booted）。
     • 确认使用的Calabash-iOS gem版本与链接到App中的Calabash.framework版本匹配。
     • 尝试在步骤定义中使用backdoor方法，调用App中的一个安全方法，检查App是否真的在运行。backdoor机制允许你在测试脚本中直接调用App的Objective-C方法，是高级调试利器。

4. 测试在CI上通过，在本地失败（或反之）

   • 原因：环境不一致。
   • 排查：检查Xcode版本、iOS模拟器版本、Ruby版本、gem包版本是否完全一致。CI环境最好使用Docker镜像或精确的版本描述文件（如.ruby-version,Gemfile.lock）来锁定环境。

从零到一搭建基于Calabash-iOS的自动化测试体系，是一个将工具、流程和团队协作紧密结合的过程。它始于一个清晰的定位——提升沟通效率和测试可维护性，成于对细节的持续打磨——稳定的元素定位、智能的等待策略、高效的CI集成。这条路走下来，最大的收获可能不是那几百个自动运行的测试用例，而是团队对质量保障达成的一种共识：自动化测试不是某个角色的任务，而是所有人共同维护的、活着的产品需求与行为规范。当你看到产品经理修改Feature文件来澄清需求，开发同学主动为UI元素添加可访问性标识时，你会明白，这套体系真正开始运转起来了。