test-xcode

# 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: - 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 - Create a P1 todo for each build error - 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 question tool — e.g., `ask_user` in Copilot CLI — or present numbered options and wait): ``` 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 - I'll help debug and fix 2. Create todo - Add a todo for later (using the todo-create skill) 3. Skip - Continue testing other screens ``` 3. **If "Fix now":** investigate, propose a fix, rebuild and retest 4. **If "Create todo":** load the `todo-create` skill and create a todo with priority p1 and description `xcode-{description}`, continue 5. **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 ### Created Todos: [count] - `006-pending-p1-xcode-settings-crash.md` ### Result: [PASS / FAIL / PARTIAL] ``` ### 9. Cleanup After testing: 1. Call `stop_log_capture` with the simulator UUID 2. Optionally call `shutdown_simulator` with the simulator UUID ## Quick Usage Examples ```bash # Test with default scheme /test-xcode # Test specific scheme /test-xcode MyApp-Debug # Test after making changes /test-xcode current ``` ## Integration with ce-review When reviewing PRs that touch iOS code, the `ce-review` workflow can spawn an agent to run this skill, build on the simulator, test key screens, and check for crashes.