xcode-test

参数

[方案名称或使用默认值的“current”]

Xcode 测试命令

<command_purpose>使用 XcodeBuildMCP 在模拟器上构建、安装和测试 iOS 应用。捕获屏幕截图和日志，并验证应用行为。</command_purpose>

简介

专注于基于模拟器进行测试的 iOS QA 工程师

此命令通过以下方式测试 iOS/macOS 应用：

• 为模拟器构建
• 安装并启动应用
• 截取关键屏幕的屏幕截图
• 捕获控制台日志以查找错误
• 支持对外部流程进行人工验证

前提条件

- 已安装带有命令行工具的 Xcode - 已连接 XcodeBuildMCP 服务 - 有效的 Xcode 项目或工作区 - 至少有一台可用的 iOS 模拟器

主要任务

0. 验证 XcodeBuildMCP 是否已安装

<check_mcp_installed>

首先，检查 XcodeBuildMCP 工具是否可用。

尝试调用：

mcp__xcodebuildmcp__list_simulators({})

如果找不到该工具或发生错误：

告知用户：

**XcodeBuildMCP not installed**

Please install the XcodeBuildMCP server first:

\`\`\`bash
claude mcp add XcodeBuildMCP -- npx xcodebuildmcp@latest
\`\`\`

Then restart Claude Code and run `/xcode-test` again.

确认 XcodeBuildMCP 正常工作之前，请勿继续。

</check_mcp_installed>

1. 发现项目和方案

<discover_project>

查找可用项目：

mcp__xcodebuildmcp__discover_projs({})

列出项目的方案：

mcp__xcodebuildmcp__list_schemes({ project_path: "/path/to/Project.xcodeproj" })

如果提供了参数：

• 使用指定的方案名称
• 或使用“current”来采用默认/上次使用的方案

</discover_project>

2. 启动模拟器

<boot_simulator>

列出可用的模拟器：

mcp__xcodebuildmcp__list_simulators({})

启动首选模拟器（推荐 iPhone 15 Pro）：

mcp__xcodebuildmcp__boot_simulator({ simulator_id: "[uuid]" })

等待模拟器就绪： 继续安装之前，请检查模拟器状态。

</boot_simulator>

3. 构建应用

<build_app>

为 iOS 模拟器构建：

mcp__xcodebuildmcp__build_ios_sim_app({
  project_path: "/path/to/Project.xcodeproj",
  scheme: "[scheme_name]"
})

处理构建失败：

• 捕获构建错误
• 为每个构建错误创建一个 P1 待办事项
• 向用户报告具体错误详情

成功后：

• 记录已构建应用的路径，以供安装
• 继续执行安装步骤

</build_app>

4. 安装并启动

<install_launch>

在模拟器上安装应用：

mcp__xcodebuildmcp__install_app_on_simulator({
  app_path: "/path/to/built/App.app",
  simulator_id: "[uuid]"
})

启动应用：

mcp__xcodebuildmcp__launch_app_on_simulator({
  bundle_id: "[app.bundle.id]",
  simulator_id: "[uuid]"
})

开始捕获日志：

mcp__xcodebuildmcp__capture_sim_logs({
  simulator_id: "[uuid]",
  bundle_id: "[app.bundle.id]"
})

</install_launch>

5. 测试关键屏幕

<test_screens>

针对应用中的每个关键屏幕：

截取屏幕截图：

mcp__xcodebuildmcp__take_screenshot({
  simulator_id: "[uuid]",
  filename: "screen-[name].png"
})

检查屏幕截图：

• UI 元素是否正确呈现
• 是否显示错误消息
• 是否显示预期内容
• 布局是否正确

检查日志中的错误：

mcp__xcodebuildmcp__get_sim_logs({ simulator_id: "[uuid]" })

查找以下内容：

• 崩溃
• 异常
• 错误级别的日志消息
• 失败的网络请求

</test_screens>

6. 人工验证（需要时）

<human_verification>

测试涉及以下流程时，请暂停并等待人工输入：

流程类型	要询问的内容
使用 Apple 登录	“请在模拟器上完成使用 Apple 登录”
推送通知	“发送一条测试推送并确认其已显示”
App 内购买	“完成一次沙盒购买”
相机/照片	“授予权限并验证相机能否正常工作”
位置	“允许访问位置信息并验证地图是否更新”

使用 AskUserQuestion：

**Human Verification Needed**

This test requires [flow type]. Please:
1. [Action to take on simulator]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

</human_verification>

7. 处理失败

<failure_handling>

测试失败时：

1. 记录失败情况：

   • 截取错误状态的屏幕截图
   • 捕获控制台日志
   • 记录复现步骤

2. 询问用户如何继续：

   **Test Failed: [screen/feature]**
   
   Issue: [description]
   Logs: [relevant error messages]
   
   How to proceed?
   1. Fix now - I'll help debug and fix
   2. Create todo - Add to todos/ for later
   3. Skip - Continue testing other screens
   

3. 如果选择“立即修复”：

   • 在代码中调查问题
   • 提出修复方案
   • 重新构建并测试

4. 如果选择“创建待办事项”：

   • 创建 {id}-pending-p1-xcode-{description}.md
   • 继续测试

</failure_handling>

8. 测试摘要

<test_summary>

所有测试完成后，展示摘要：

## 📱 Xcode Test Results

**Project:** [project name]
**Scheme:** [scheme name]
**Simulator:** [simulator name]

### Build: ✅ Success / ❌ Failed

### Screens Tested: [count]

| Screen | Status | Notes |
|--------|--------|-------|
| Launch | ✅ Pass | |
| Home | ✅ Pass | |
| Settings | ❌ Fail | Crash on tap |
| Profile | ⏭️ Skip | Requires login |

### Console Errors: [count]
- [List any errors found]

### Human Verifications: [count]
- Sign in with Apple: ✅ Confirmed
- Push notifications: ✅ Confirmed

### Failures: [count]
- Settings screen - crash on navigation

### Created Todos: [count]
- `006-pending-p1-xcode-settings-crash.md`

### Result: [PASS / FAIL / PARTIAL]

</test_summary>

9. 清理

测试完成后：

停止日志捕获：

mcp__xcodebuildmcp__stop_log_capture({ simulator_id: "[uuid]" })

可选择关闭模拟器：

mcp__xcodebuildmcp__shutdown_simulator({ simulator_id: "[uuid]" })

快速使用示例

# Test with default scheme
/xcode-test

# Test specific scheme
/xcode-test MyApp-Debug

# Test after making changes
/xcode-test current

与 /workflows:review 集成

审查涉及 iOS 代码的 PR 时，/workflows:review 命令可以将此命令作为子 Agent 启动：

Task general-purpose("Run /xcode-test for scheme [name]. Build, install on simulator, test key screens, check for crashes.")