git:20260818.459c9eb to git:20260820.15ab6f7

13 added, 195 removed. Audit A to A.

---

name: ce-test-xcode

- description: "Build and test iOS apps on simulator with XcodeBuildMCP."

+ description: "Test iOS apps in a simulator with XcodeBuildMCP. Use when iOS changes need simulator evidence before handoff."

argument-hint: "[scheme name or 'current' to use default]"

disable-model-invocation: true

---

- # Xcode Test Skill

- Build, install, and test iOS apps on the simulator using XcodeBuildMCP. Captures screenshots, logs, and verifies app behavior.

- ## Prerequisites

- - Xcode installed with command-line tools

- - XcodeBuildMCP MCP server connected

- - Valid Xcode project or workspace

- - At least one iOS Simulator available

- ## Workflow

- ### 0. Verify XcodeBuildMCP is Available

- Check that the XcodeBuildMCP MCP server is connected by calling its `list_simulators` tool.

- MCP tool names vary by platform:

- - Claude Code: `mcp__xcodebuildmcp__list_simulators`

- - Other platforms: use the equivalent MCP tool call for the `XcodeBuildMCP` server's `list_simulators` method

- If the tool is not found or errors, inform the user they need to add the XcodeBuildMCP MCP server:

- ```

- XcodeBuildMCP not installed

- Install via Homebrew:

- brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp

- Or via npx (no global install needed):

- npx -y xcodebuildmcp@latest mcp

- Then add "XcodeBuildMCP" as an MCP server in your agent configuration

- and restart your agent.

- ```

- Do NOT proceed until XcodeBuildMCP is confirmed working.

- ### 1. Discover Project and Scheme

- Call XcodeBuildMCP's `discover_projs` tool to find available projects, then `list_schemes` with the project path to get available schemes.

- If an argument was provided, use that scheme name. If "current", use the default/last-used scheme.

- ### 2. Boot Simulator

- Call `list_simulators` to find available simulators. Boot the preferred simulator (iPhone 15 Pro recommended) using `boot_simulator` with the simulator's UUID.

- Wait for the simulator to be ready before proceeding.

- ### 3. Build the App

- Call `build_ios_sim_app` with the project path and scheme name.

- **On failure:**

- - Capture build errors

- - Report to user with specific error details

- **On success:**

- - Note the built app path for installation

- - Proceed to step 4

- ### 4. Install and Launch

- 1. Call `install_app_on_simulator` with the built app path and simulator UUID

- 2. Call `launch_app_on_simulator` with the bundle ID and simulator UUID

- 3. Call `capture_sim_logs` with the simulator UUID and bundle ID to start log capture

- ### 5. Test Key Screens

- For each key screen in the app:

- **Take screenshot:**

- Call `take_screenshot` with the simulator UUID and a descriptive filename (e.g., `screen-home.png`).

- **Review screenshot for:**

- - UI elements rendered correctly

- - No error messages visible

- - Expected content displayed

- - Layout looks correct

- **Check logs for errors:**

- Call `get_sim_logs` with the simulator UUID. Look for:

- - Crashes

- - Exceptions

- - Error-level log messages

- - Failed network requests

- **Known automation limitation — SwiftUI Text links:**

- Simulated taps (via XcodeBuildMCP or any simulator automation tool) do not trigger gesture recognizers on SwiftUI `Text` views with inline `AttributedString` links. Taps report success but have no effect. This is a platform limitation — inline links are not exposed as separate elements in the accessibility tree. When a tap on a Text link has no visible effect, prompt the user to tap manually in the simulator. If the target URL is known, `xcrun simctl openurl <device> <URL>` can open it directly as a fallback.

- ### 6. Human Verification (When Required)

- Pause for human input when testing touches flows that require device interaction.

- | Flow Type | What to Ask |

- |-----------|-------------|

- | Sign in with Apple | "Please complete Sign in with Apple on the simulator" |

- | Push notifications | "Send a test push and confirm it appears" |

- | In-app purchases | "Complete a sandbox purchase" |

- | Camera/Photos | "Grant permissions and verify camera works" |

- | Location | "Allow location access and verify map updates" |

- | SwiftUI Text links | "Please tap on [element description] manually — automated taps cannot trigger inline text links" |

- Ask the user using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options on the host's user-visible chat surface only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question:

- ```

- 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

- ```

- ### 7. Handle Failures

- When a test fails:

- 1. **Document the failure:**

- - Take screenshot of error state

- - Capture console logs

- - Note reproduction steps

- 2. **Ask the user how to proceed:**

- ```

- Test Failed: [screen/feature]

- Issue: [description]

- Logs: [relevant error messages]

- How to proceed?

- 1. Fix now - debug, propose a fix, rebuild and retest

- 2. Skip - continue testing other screens

- ```

- 3. **If "Fix now":** investigate, propose a fix, rebuild and retest

- 4. **If "Skip":** log as skipped, continue

- ### 8. Test Summary

- After all tests complete, present a summary:

- ```markdown

- ## 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

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

- ```

- ### 9. Cleanup

- After testing:

+ # Xcode Simulator Test

- 1. Call `stop_log_capture` with the simulator UUID

- 2. Optionally call `shutdown_simulator` with the simulator UUID

+ Build and exercise an iOS app on a simulator, preserving screenshots, logs, human-verification results, and failures as evidence for the user.

- ## Quick Usage Examples

+ **Done:**

- ```bash

- # Test with default scheme

- /ce-test-xcode

+ - A completed run reports overall `PASS`, `FAIL`, or `PARTIAL` plus project, scheme, simulator, build result, per-surface `PASS` / `FAIL` / `SKIP`, console errors, human checks, and residual failures.

+ - Per-surface status is derived from evidence, not the user's routing choice. `PASS` requires completed passing evidence. `FAIL` records observed failing evidence until a completed retest replaces it. `SKIP` means the check has no completed outcome.

+ - The overall result is `FAIL` while any failure remains, `PARTIAL` when no failure remains but a scoped check is skipped, and otherwise `PASS`.

+ - Any failure before the launched-with-log-capture handoff stops later stages and reports an actionable setup blocker with its evidence.

- # Test specific scheme

- /ce-test-xcode MyApp-Debug

+ **Boundaries:** this skill tests and reports. Diagnosis and any user-approved product fix belong to `ce-debug`, invoked with authority narrowed to return here without committing, pushing, or opening a PR. Keep simulator interaction within the app and flows the user placed in scope.

- # Test after making changes

- /ce-test-xcode current

- ```

+ ## Run

- ## Integration with ce-code-review

+ 1. **Prepare and launch.** Read `references/setup-and-build.md`. It owns the XcodeBuildMCP availability gate, project and scheme discovery, simulator choice, build, install, launch, and log-capture start.

+ 2. **Exercise and report.** After launch, read `references/test-and-report.md`. It owns per-screen evidence, human-only flows, the SwiftUI inline-link automation limitation, failure routing, cleanup, and the fixed summary fields.

- When reviewing PRs that touch iOS code, the `ce-code-review` workflow can spawn an agent to run this skill, build on the simulator, test key screens, and check for crashes.

+ Do not replace either required read with remembered tool names. XcodeBuildMCP adapters differ by host, while their observable success conditions do not.