# ios-simulator

> iOS Simulator control for visual QA, screenshots, and UI testing. Use when you need to build, install, launch the app, take screenshots, or run UI tests.

- Author: Brendan Smith
- Repository: bsmith24/orc
- Version: 20251221053040
- Stars: 13
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/bsmith24/orc
- Web: https://mule.run/skillshub/@@bsmith24/orc~ios-simulator:20251221053040

---

---
name: ios-simulator
description: iOS Simulator control for visual QA, screenshots, and UI testing. Use when you need to build, install, launch the app, take screenshots, or run UI tests.
---

# iOS Simulator Control

## Finding Simulator ID

List available simulators:
```bash
xcrun simctl list devices available
```

Use the UUID of your target device (e.g., iPhone 16 Pro).

---

## Quick Commands

Replace `$SIMULATOR_ID`, `$PROJECT`, `$SCHEME`, `$BUNDLE_ID` with actual values.

### Boot Simulator
```bash
xcrun simctl boot $SIMULATOR_ID 2>/dev/null || true
open -a Simulator
```

### Build App
```bash
xcodebuild build \
  -project $PROJECT/$SCHEME.xcodeproj \
  -scheme $SCHEME \
  -sdk iphonesimulator \
  -configuration Debug \
  -derivedDataPath $PROJECT/build/DerivedData
```

### Install App
```bash
xcrun simctl install $SIMULATOR_ID \
  $PROJECT/build/DerivedData/Build/Products/Debug-iphonesimulator/$SCHEME.app
```

### Launch App
```bash
xcrun simctl launch $SIMULATOR_ID $BUNDLE_ID
```

### Take Screenshot
```bash
mkdir -p $PROJECT/build/screenshots
xcrun simctl io $SIMULATOR_ID screenshot $PROJECT/build/screenshots/[name].png
```

### Analyze Screenshot
Use the `Read` tool on the PNG file - Claude can see images:
```
Read: $PROJECT/build/screenshots/[name].png
```

---

## Run Unit Tests

```bash
xcodebuild test \
  -project $PROJECT/$SCHEME.xcodeproj \
  -scheme $SCHEME \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,id=$SIMULATOR_ID' \
  -derivedDataPath $PROJECT/build/DerivedData
```

---

## Run UI Tests

```bash
killall Simulator 2>/dev/null || true && \
xcrun simctl shutdown all 2>/dev/null || true && \
sleep 2 && \
xcrun simctl boot $SIMULATOR_ID && \
open -a Simulator && \
sleep 5 && \
xcrun simctl uninstall $SIMULATOR_ID $BUNDLE_ID 2>/dev/null || true && \
xcrun simctl privacy $SIMULATOR_ID grant location $BUNDLE_ID && \
xcodebuild test \
  -project $PROJECT/$SCHEME.xcodeproj \
  -scheme $SCHEME \
  -only-testing:${SCHEME}UITests \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,id=$SIMULATOR_ID' \
  -parallel-testing-enabled NO \
  -derivedDataPath $PROJECT/build/DerivedData
```

---

## Visual QA Workflow

### Screenshot Naming Convention
```
build/screenshots/[screen]_[state].png

Examples:
- camera_default.png
- library_empty.png
- library_with_data.png
- detail_playing.png
```

### Headless Screenshots (Preferred)

**IMPORTANT: Screenshots can be captured WITHOUT opening Simulator.app window.**

The simulator runs headlessly during `xcodebuild test` - no visible window needed:
- Simulator boots in background
- App launches and runs
- Screenshot captured via `xcrun simctl io`
- Simulator shuts down

**Benefits:**
- ✅ Works in CI/CD environments (no display required)
- ✅ Faster (no GUI overhead)
- ✅ No accidental window interactions
- ✅ Cleaner automation

**How it works:**
```bash
# xcodebuild test boots simulator headlessly
xcodebuild test -project ... -destination 'platform=iOS Simulator,id=$SIMULATOR_ID' ...

# While app is running, capture screenshot
xcrun simctl io $SIMULATOR_ID screenshot build/screenshots/[name].png
```

**Note:** Only use `open -a Simulator` if you specifically need to see the UI during debugging.

### Workflow Steps

1. **Build & Install**: Build app, install on simulator
2. **Launch**: `xcrun simctl launch $SIMULATOR_ID $BUNDLE_ID`
3. **Navigate**: Reach target screen
4. **Screenshot**: `xcrun simctl io $SIMULATOR_ID screenshot build/screenshots/[name].png`
5. **Analyze**: Use Read tool on PNG - Claude can see and analyze images
6. **Brand Check**: Compare against brand.md (see checklist below)
7. **Report**: Document findings with pass/fail for each item

---

## Brand Compliance Analysis

After capturing a screenshot, use the Read tool to view it, then verify:

### 1. COLORS
Compare to brand.md color palette:
- [ ] Background color correct?
- [ ] Accent/primary color correct?
- [ ] Text colors correct (headings, body, secondary)?
- [ ] No unexpected colors?

### 2. TYPOGRAPHY
- [ ] Body text ≥17pt?
- [ ] Caption/secondary text ≥13pt?
- [ ] Font weights appropriate (bold for headers, regular for body)?
- [ ] No ALL CAPS for labels?

### 3. SPACING & LAYOUT
- [ ] Margins consistent (typically 16-20pt horizontal)?
- [ ] Component spacing uniform?
- [ ] Touch targets ≥44pt?
- [ ] Content not too cramped or too sparse?

### 4. CONSISTENCY
- [ ] Tab bar matches other screens?
- [ ] Nav bar matches other screens?
- [ ] Same components styled identically everywhere?
- [ ] No duplicate information on same screen?

### 5. BRAND FEEL
- [ ] Does it feel like the brand.md describes (warm, minimal, bold, etc.)?
- [ ] Consistent with the app's overall aesthetic?
- [ ] Would a user recognize this as part of the same app?

### Report Format
```
VISUAL VERIFICATION:
Screenshot: build/screenshots/[name].png

Brand Compliance:
- Colors: PASS/FAIL - [details]
- Typography: PASS/FAIL - [details]
- Spacing: PASS/FAIL - [details]
- Consistency: PASS/FAIL - [details]
- Brand feel: PASS/FAIL - [details]

Overall: APPROVED / NEEDS REVISION
Issues: [list specific problems]
```

---

## Troubleshooting

### Simulator won't boot
```bash
xcrun simctl shutdown all
killall Simulator
xcrun simctl boot $SIMULATOR_ID
```

### App won't install
Check the build succeeded and `.app` exists:
```bash
ls $PROJECT/build/DerivedData/Build/Products/Debug-iphonesimulator/
```

### Location permissions
Grant before launching:
```bash
xcrun simctl privacy $SIMULATOR_ID grant location $BUNDLE_ID
```

### Find Bundle ID
Check the project's Info.plist or:
```bash
grep -r "PRODUCT_BUNDLE_IDENTIFIER" $PROJECT/*.xcodeproj/project.pbxproj | head -1
```