xcode-simulator-testing

Xcode simulator test

Contract

Inputs

• Scheme argument (optional): empty or current selects the default or last-used scheme; a named argument selects that scheme. Ask only when the scheme cannot be resolved or project discovery is materially ambiguous.
• The user's request and the changed iOS surface define the screens and flows to exercise.
• Required environment, which this skill does not install or configure: XcodeBuildMCP connected as an MCP server, Xcode and its command-line tools, a valid project or workspace, and an available iOS simulator.

Procedure

1. Run the availability gate. Confirm that the active harness exposes XcodeBuildMCP's simulator-listing capability and that the call succeeds; host-specific MCP tool prefixes are adapters, not the contract. If the capability is absent or errors, stop before discovery or build. Report that XcodeBuildMCP must be installed and connected, give the user these setup options to run: brew tap getsentry/xcodebuildmcp && brew install xcodebuildmcp or pnpm dlx xcodebuildmcp@latest mcp, and tell the user to add XcodeBuildMCP as an MCP server and restart the agent. Also stop and report a missing prerequisite when Xcode, its command-line tools, a valid project or workspace, or an iOS simulator is unavailable. Done when: all prerequisites are confirmed available and XcodeBuildMCP's simulator-listing capability succeeds.
2. Discover projects and workspaces, then list schemes for the selected project. Resolve the scheme from the argument. List simulators; reuse a compatible booted simulator when practical, otherwise prefer an available iPhone 15 Pro and boot it by UUID, and wait until it is ready. Done when: the project, scheme, and simulator are resolved and the simulator is booted and ready.
3. Build the simulator app with the selected project or workspace and scheme. On failure, report the relevant build errors and stop; do not install or launch a missing artifact. Done when: the simulator app is built successfully.
4. From the successful build result, retain the app path and bundle identifier. Install the app, launch it, and start simulator log capture for that bundle. Retain the project or workspace, scheme, simulator identity, app identity, and log-capture handle. Any failure before the app is visibly launched with log capture running is a setup blocker: preserve its evidence, report it, and stop later stages. Done when: the app is installed, launched, and log capture is running.
5. Derive the key screens and flows from the user's request and the changed iOS surface. For each one, navigate through the running app and record what you exercised. Capture a descriptively named screenshot of the resulting state. Check that the expected content and controls render without visible errors or broken layout. Read the captured simulator logs for crashes, exceptions, error-level messages, and failed network requests attributable to the flow. A simulated action reporting success does not prove the expected state change; verify the visible result or logs. Done when: every key screen and flow is exercised with a screenshot and log review.
6. SwiftUI inline Text links: simulated taps do not trigger gesture recognizers on SwiftUI Text views with inline AttributedString links because the link is not exposed as a separate accessibility element. When such a tap reports success but has no visible effect, ask the user to tap the link manually in the simulator. If the target URL is known, fall back to xcrun simctl openurl <device-uuid> <URL>. Record which fallback supplied the verification; do not report the automated tap itself as a pass. Done when: the inline-link interaction is verified via manual tap or simctl openurl fallback.
7. Pause for human-only verification only when the scoped flow requires interaction that the available simulator automation cannot complete: Sign in with Apple, push delivery, a sandbox purchase, camera or photos permission, location permission, or the inline-link case. State the exact action and expected observation, then ask whether it worked. Derive status from evidence, not the user's next-action choice: PASS requires a completed passing outcome, FAIL records a completed failing outcome, and SKIP applies only to a check with no completed outcome. An unanswered check is SKIP for that surface. Never silently mark an unanswered or failed check as passed. Done when: every human-only verification is asked with its exact action and expected observation, and status is derived from the response.
8. Derive per-surface status from evidence: PASS requires completed passing evidence; FAIL records observed failing evidence until a completed retest replaces it; SKIP means the check has no completed outcome. Roll up the overall result: FAIL while any failure remains, PARTIAL when no failure remains but a scoped check is skipped, and otherwise PASS. Done when: per-surface status and overall result are derived from evidence.
9. Stop the log capture started by this run. Leave a simulator that was already booted as found; a simulator booted only for this run may be shut down after evidence is saved. Done when: log capture is stopped and simulator state is handled.