ios-simulator

name	ios-simulator
description	Automate iOS Simulator tasks — capture screenshots, interact with apps, generate screen flow galleries. Use when the user asks to capture app screens, screenshot the simulator, document the app UI, create a screen flow, interact with the simulator, or automate iOS testing workflows.
license	Apache-2.0
metadata	{"status":"experimental","experimental_reason":"Simulator automation remains sensitive to local device state, timing, window focus, and Xcode version differences."}

iOS Simulator

Automate iOS Simulator workflows: build, launch, interact with apps, and capture artifacts.

Fundamentals

Build and launch

cd <project-dir>
xcodegen generate 2>&1  # if project.yml exists
xcodebuild -project *.xcodeproj -scheme <scheme> \
  -destination 'platform=iOS Simulator,name=<device>' build 2>&1 | tail -5
xcrun simctl boot "<device>" 2>&1 || true
open -a Simulator
APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData/<project>-*/Build/Products/Debug-iphonesimulator/*.app -maxdepth 0 | head -1)
xcrun simctl install "<device>" "$APP_PATH"
xcrun simctl launch "<device>" <bundle-id>
sleep 3

Simulator interaction

See references/simulator-interaction.md for coordinate mapping, click patterns, and device info.

Key constraints

• Simulator clicks are unreliable for nav bar buttons and back navigation
• Always relaunch app to navigate to deep screens rather than trying back buttons
• Wait 3+ seconds after launch before clicking
• Use focus click + real click pattern for reliable interaction
• Query window position fresh each time — it shifts between sessions

Workflows

Workflow	When to use
Capture Screens	Screenshot each screen in a user flow and generate an HTML gallery