/ce-test-xcode

面向用户的技能文档 docs/skills/ce-test-xcode.zh-CN.md

ce-test-xcode

使用 XcodeBuildMCP 在模拟器上构建和测试 iOS 应用程序 — 捕获屏幕截图、日志并验证关键屏幕上的应用程序行为。

ce-test-xcode 是 iOS 模拟器测试 技能。它构建您的 iOS 项目，启动模拟器，安装并启动应用程序，跨关键屏幕捕获屏幕截图和日志，暂停以对需要设备交互的流程进行人工验证（使用 Apple 登录、推送、应用内购买、相机/照片、位置），并生成结构化测试摘要。 Beta 风格的行为 (disable-model-invocation: true) — 仅显式调用。

TL;DR

问题 回答
它有什么作用？ 在模拟器上构建、安装并启动 iOS 应用程序；截屏；检查日志中是否有错误；暂停对纯设备流程进行人工验证
何时使用它 进行 iOS 代码更改后；创建 PR 之前；验证应用程序行为或检查模拟器上的崩溃时
它生产什么 屏幕截图、捕获的日志和结构化测试摘要（每个屏幕通过/失败、控制台错误、人工验证、总体结果）
状态 仅显式调用 (disable-model-invocation: true)

＃＃ 问题

手动 iOS 模拟器测试缓慢且不一致：

  • 构建 → 安装 → 启动 → 练习 → 屏幕截图 是每次更改都需要执行的 5 个以上步骤
  • 日志丢失 - 没有显式捕获，控制台错误在模拟器重新启动时消失
  • 没有结构化摘要 - “我测试了它，看起来不错”没有显示测试过的内容或跳过的内容
  • 仅限设备的流程无法自动化 - 使用 Apple 登录、沙盒购买、推送通知需要人工参与，但很容易忘记并跳过它们
  • SwiftUI 内联链接不响应模拟点击 — 点击报告成功但没有效果；这让团队措手不及
  • 没有可共享的工件 - 屏幕截图和日志最终出现在开发人员的文件系统中，而不是 PR 描述中

解决方案

ce-test-xcode 将模拟器测试作为具有显式门的结构化流程运行：

  • 飞行前检查 在接触任何内容之前确认 XcodeBuildMCP 已连接
  • 项目 + 方案发现 自动检测要构建的内容，并覆盖用户提供的方案
  • 构建、安装、启动、日志捕获作为具有故障处理功能的离散 MCP 调用
  • 逐屏测试，包括屏幕截图、日志检查以及每个屏幕的通过/失败
  • 人工验证步骤，适用于需要设备交互的流程（带有 SwiftUI 内联链接的记录解决方法）
  • 故障处理询问用户如何继续（立即修复或跳过）而不是默默中止
  • 结构化测试摘要，包含每个屏幕的状态、控制台错误、人工验证和总体结果

是什么让它如此新颖

1. XcodeBuildMCP作为基底

该技能使用 Sentry 的 XcodeBuildMCP — 一个 MCP 服务器，它将 Xcode 项目发现、模拟器管理、构建/安装/启动、日志捕获和屏幕截图捕获作为工具调用公开。这意味着该技能本身是 MCP 工具上的精简编排器，而不是 xcodebuild shell 调用的包装器：

  • discover_projs — 在工作区中查找 Xcode 项目
  • list_schemes — 获取项目的可用方案
  • list_simulators、boot_simulator、shutdown_simulator — 模拟器管理
  • build_ios_sim_app — 为模拟器构建
  • install_app_on_simulator、launch_app_on_simulator — 安装 + 启动
  • take_screenshot、capture_sim_logs、get_sim_logs、stop_log_capture — 观察

当 XcodeBuildMCP 不可用时，该技能会停止并提供安装说明 - 它不会尝试后备路径。

2.结构化测试流程，而不是shell脚本

每个阶段都是一个明确的步骤：发现、启动、构建、安装、启动、日志捕获、测试屏幕、处理故障、摘要、清理。每个步骤都有失败处理。这会产生一个可在聊天中审核的测试运行 - 您可以看到测试了哪些内容、通过了哪些内容、跳过了哪些内容。

3. 人工验证步骤 — 使用 Apple 登录、IAP、推送、相机、位置

有些流程无法在模拟器上自动化：

流量 人工验证的要求是什么？
使用 Apple 登录 “请在模拟器上完成使用 Apple 登录”
推送通知 “发送测试推送并确认其出现”
应用内购买 “完成沙盒购买”
相机/照片 “授予权限并验证相机是否正常工作”
地点 “允许位置访问并验证地图更新”

该技能因阻塞问题而暂停，用户在模拟器上执行该操作，然后回答是（继续）或否（描述问题）。这使得仅设备流变得明确，而不是默默地跳过。

4. 记录的平台限制 — SwiftUI 文本链接

模拟点击不会触发具有内联 AttributedString 链接的 SwiftUI Text 视图上的手势识别器 - 它们报告成功但没有效果。这是一个平台限制（内联链接不会作为可访问性树中的单独元素公开）。该技能知道这一点，并当内联链接不响应时提示用户手动点击，并在目标 URL 已知时记录 xcrun simctl openurl 回退。

5. 故障处理 — 立即修复或跳过

当屏幕出现故障时，技能会捕获错误状态（屏幕截图+控制台日志+重现步骤）并询问用户如何继续：

  • 立即修复 — 调查、提出修复建议、重建、重新测试
  • 跳过 — 记录为已跳过，继续测试其他屏幕

任一路径均有效。重点是明确选择，而不是在第一次失败时默默中止。

6.结构化测试总结

测试所有屏幕后，该技能会生成一个 Markdown 摘要：

  • 项目名称、方案、模拟器
  • 构建状态（成功/失败）
  • 每个屏幕的状态表（通过/失败/跳过带注释）
  • 发现控制台错误
  • 人工验证已完成
  • 总体结果（通过/失败/部分）

这适合粘贴到 PR 描述或发布准备报告中。

7. 仅 Beta 式显式调用

frontmatter 中的 disable-model-invocation: true 会阻止该技能自动发射。模拟器测试是一个深思熟虑的选择——你不希望它作为询问其他事情的副作用而被触发。直接调用/ce-test-xcode。

简单示例

您完成了配置文件编辑屏幕的 iOS 功能。您调用 /ce-test-xcode。

该技能调用 XcodeBuildMCP 的 list_simulators 来验证 MCP 是否已连接。然后 discover_projs 找到你的 Xcode 项目； list_schemes 返回三；您没有传递参数，因此它选择默认的上次使用的方案。

启动 iPhone 15 Pro 模拟器。使用 build_ios_sim_app 构建 — 成功。通过 install_app_on_simulator 和 launch_app_on_simulator 安装和启动。开始日志捕获。

测试关键屏幕：启动（屏幕截图，无错误）、主页（屏幕截图，无错误）、个人资料（屏幕截图 - 但路径中包含“使用 Apple 登录”流程）。该技能暂停以进行人工验证：“请在模拟器上完成使用 Apple 登录。”您可以在模拟器上点击它。回答“是的——继续测试。”配置文件屏幕已测试 - 屏幕截图，没有错误。设置（屏幕截图 - 点击“隐私”行时崩溃）。该技能捕获崩溃日志，显示故障，并询问：立即修复还是跳过？

您选择“立即修复”。该技能会调查崩溃日志、识别缺失的 nil 检查、提出修复建议、重建、重新安装、重新测试设置 — 通过。

在所有屏幕之后，测试摘要落地：测试了 4 个屏幕，0 个控制台错误，确认了 1 个人工验证，在测试期间应用了 1 个修复。总体结果：通过。

该技能会停止日志捕获并可选择关闭模拟器。

何时去实现它

在以下情况下使用 ce-test-xcode：

  • 您已完成 iOS 代码更改并希望在打开 PR 之前进行验证
  • 重构后您正在检查模拟器上的崩溃情况
  • PR 包括需要视觉验证的 UI 更改
  • 您需要使用结构化包装器手动执行仅限设备的流程（使用 Apple 登录、IAP、推送）
  • 您想要一个适合 PR 描述的测试摘要

在以下情况下跳过 ce-test-xcode：

  • 更改是非 UI 的（仅模型层，具有单元测试覆盖范围的内部服务）
  • XcodeBuildMCP 不可用 — 该技能随着安装说明而停止；先安装它
  • 您想要单元测试验证 → 直接使用 xcodebuild test 或您项目的测试运行程序
  • 你不在 macOS / 没有 Xcode → 该技能将无法发挥作用

用作工作流程的一部分

ce-test-xcode 与验证侧链的其余部分互锁：

  • /ce-code-review 第 2 层 — 在审查涉及 iOS 的 PR 时，工作流程可以生成一个代理来运行此技能、在模拟器上构建、测试关键屏幕并检查崩溃
  • /ce-work 第 3 阶段/第 4 阶段 — 在针对 iOS 密集型工作打开 PR 之前合适；测试摘要成为 PR 描述验证叙述的一部分

该技能的输出（测试摘要）是包含在 PR 描述中的合适证据，补充了 /ce-demo-reel 为视觉演示生成的内容。

使用独立版

最直接的使用：

  • 默认方案 — /ce-test-xcode
  • 具体方案 — /ce-test-xcode MyApp-Debug
  • 上次使用 — /ce-test-xcode current

该技能发现项目，选择模拟器（推荐 iPhone 15 Pro），然后运行完整流程。当 XcodeBuildMCP 丢失时，技能将停止并显示安装说明：

通过自制程序安装：
  酿造水龙头getentry/xcodebuildmcp && 酿造安装xcodebuildmcp

或者通过 npx：
  npx -y xcodebuildmcp@最新 mcp

然后在代理配置中添加“XcodeBuildMCP”作为 MCP 服务器
并重新启动您的代理。

＃＃ 参考

论证 效果
（空） 发现项目+使用默认方案
<scheme name> <scheme name>使用该方案构建
current 使用默认/上次使用的方案

必需：XcodeBuildMCP MCP 服务器已连接。自动检测：Xcode 项目、可用模拟器（存在时首选 iPhone 15 Pro）。

＃＃ 常问问题

为什么使用 XcodeBuildMCP 而不是直接使用 xcodebuild？ 因为MCP服务器提供了更高级别的语义（项目发现、模拟器启动/关闭、屏幕截图、日志捕获）作为工具调用。该技能成为一个精简的编排器，而不是 shell 脚本包装器，并且特定于平台的边缘情况（模拟器状态、日志捕获生命周期）由 MCP 处理。

如果点击 SwiftUI 文本链接不起作用怎么办？ 已知的平台限制 - 模拟点击不会触发内联 AttributedString 链接上的手势识别器。该技能会提示您在模拟器中手动点击。如果目标 URL 已知，xcrun simctl openurl <device> <URL> 会直接打开它作为后备。

为什么只是显式调用？ 因为 disable-model-invocation: true 会阻止技能自动发射。模拟器测试是一个经过深思熟虑的用户选择——您不希望它在您刚刚要求代理查看某些内容时触发。直接调用/ce-test-xcode。

UI 测试 (XCUITest) 怎么样？ 此技能通过模拟器交互（点击、屏幕截图、日志检查）而不是通过 XCUITest 脚本来练习正在运行的应用程序。对于单元/UI 测试运行，请使用 xcodebuild test 或项目的运行程序。两者相辅相成。

没有 iPhone 15 Pro 可以运行吗？ 是的 — list_simulators 返回任何可用的内容；技能选其一。 iPhone 15 Pro 是推荐的默认配置，但不是必需的。

如果构建失败怎么办？ 该技能捕获构建错误并报告它们的具体细节。它不会在失败的构建上继续安装/启动。

另请参阅

  • ce-code-review — 可以为涉及 iOS 的 PR 生成此技能作为验证步骤
  • ce-test-browser — 通过代理浏览器进行 Web 应用程序测试的同级技能
  • ce-demo-reel — 捕获 PR 描述的视觉证据；测试总结的补充
  • ce-work — 可以在第 3 阶段验证期间调用此技能的编排器

← 返回技能概览