name: ios-build-verify
description: iOS build, test, and simulator verification expert. Builds Xcode projects, runs tests, manages iOS Simulators, captures screenshots, parses xcresult bundles, and diagnoses build failures. Use when building iOS apps from the command line, running on simulators, extracting test results, or troubleshooting xcodebuild errors.

iOS Build, Test, and Simulator Verification

Overview

Building and testing iOS apps from the command line is the foundation of every CI pipeline and autonomous development workflow. This skill covers the entire loop: build the app, run it on a simulator, capture evidence (screenshots, test results), and diagnose failures when things go wrong.

Use this skill when:
- Building an iOS project with xcodebuild from the terminal
- Running apps on iOS Simulators without opening Xcode
- Extracting pass/fail results and code coverage from .xcresultbundle files
- Diagnosing build errors (missing modules, signing, linker failures)
- Setting up CI pipelines that build, test, and report

Core Workflow

Every build-verify cycle follows this pipeline:

Discover (schemes/targets) -> Build -> Install on Simulator -> Launch -> Verify (screenshot/tests) -> Parse Results

Each step has specific tools, flags, and failure modes. This skill covers all of them.

Decision Trees

Build Failing?

What is the error?
|
+-- "No such module 'X'"
|   SPM: xcodebuild -resolvePackageDependencies
|   CocoaPods: pod install, use .xcworkspace not .xcodeproj
|   Manual framework: check target membership and FRAMEWORK_SEARCH_PATHS
|   Reference: references/build-troubleshooting.md
|
+-- "Signing requires a development team"
|   CI: add CODE_SIGNING_ALLOWED=NO to xcodebuild invocation
|   Local: set team in Xcode project or pass DEVELOPMENT_TEAM=XXXX
|   Reference: references/build-troubleshooting.md
|
+-- "Cannot find type 'X' in scope"
|   Check import statements at top of file
|   Verify file is in correct target (File Inspector -> Target Membership)
|   Clean derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
|   Reference: references/build-troubleshooting.md
|
+-- "Module compiled with Swift X.Y cannot be imported by Swift X.Z"
|   Rebuild all dependencies with current Swift toolchain
|   SPM: rm -rf .build && swift package resolve
|   CocoaPods: pod deintegrate && pod install
|   Reference: references/build-troubleshooting.md
|
+-- Linker error (undefined symbol / duplicate symbol)
|   Undefined: check linked frameworks, OTHER_LDFLAGS, -ObjC flag
|   Duplicate: check for files included in multiple targets
|   Reference: references/build-troubleshooting.md
|
+-- "The sandbox is not in sync with the Podfile.lock"
|   Run: pod install
|   Reference: references/build-troubleshooting.md
|
+-- Other / Unknown
    Capture full log: xcodebuild ... 2>&1 | tee build.log
    Search: grep -n "error:" build.log
    Reference: references/xcodebuild-commands.md

Need to Test on Simulator?

Do you have the right simulator?
|
+-- Don't know what's available:
|   xcrun simctl list devices available
|   Reference: references/simulator-management.md
|
+-- Need a specific device/OS:
|   xcrun simctl create "Test-iPhone16" "iPhone 16" iOS18.2
|   Reference: references/simulator-management.md
|
+-- Have the right simulator:
    Is it booted?
    |
    +-- NO: xcrun simctl boot <device>
    +-- YES: Ready for install/test
    |
    Running tests?
    +-- YES: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
    |   -resultBundlePath TestResults.xcresult
    |   Reference: references/xcodebuild-commands.md
    |
    +-- NO, just need to run the app:
        xcodebuild build -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
        xcrun simctl install booted path/to/MyApp.app
        xcrun simctl launch booted com.example.MyApp
        xcrun simctl io booted screenshot verification.png
        Reference: scripts/build-and-run.sh

Need to Parse Test Results?

Do you have an .xcresultbundle?
|
+-- NO: Run tests with -resultBundlePath flag
|   xcodebuild test ... -resultBundlePath TestResults.xcresult
|   Reference: references/xcodebuild-commands.md
|
+-- YES:
    What do you need?
    |
    +-- Pass/fail summary: scripts/parse-xcresult.sh TestResults.xcresult
    +-- Code coverage: xcrun xccov view --report TestResults.xcresult
    +-- Failure details: xcrun xcresulttool get --format json --path TestResults.xcresult
    +-- Screenshots: xcrun xcresulttool export --type attachments --path TestResults.xcresult --output-path ./attachments
    Reference: references/xcresult-parsing.md

End-to-End Workflow

Build an app, run it on a fresh simulator, and capture a screenshot:

# 1. Discover available schemes
xcodebuild -list

# 2. Build for the simulator
xcodebuild build \
  -scheme "MyApp" \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -derivedDataPath build/DerivedData \
  CODE_SIGNING_ALLOWED=NO

# 3. Boot a simulator
xcrun simctl boot "iPhone 16"

# 4. Install the built app
APP_PATH=$(find build/DerivedData -name "*.app" -path "*/Debug-iphonesimulator/*" | head -1)
xcrun simctl install booted "$APP_PATH"

# 5. Launch the app
BUNDLE_ID=$(defaults read "$APP_PATH/Info.plist" CFBundleIdentifier)
xcrun simctl launch booted "$BUNDLE_ID"

# 6. Wait for launch, then capture screenshot
sleep 3
xcrun simctl io booted screenshot screenshot.png

# 7. Shutdown
xcrun simctl shutdown booted

Run tests and extract results:

# 1. Run tests with result bundle
xcodebuild test \
  -scheme "MyApp" \
  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
  -resultBundlePath TestResults.xcresult \
  CODE_SIGNING_ALLOWED=NO

# 2. Parse results
xcrun xcresulttool get --format json --path TestResults.xcresult

# 3. Get coverage
xcrun xccov view --report TestResults.xcresult

# 4. Or use the convenience script
bash scripts/parse-xcresult.sh TestResults.xcresult

Quick Reference: Verification Commands

Resources

references/

Comprehensive documentation loaded as needed:

• xcodebuild-commands.md -- Build, test, archive, export commands with all flags, destinations, and error parsing patterns
• simulator-management.md -- Full xcrun simctl lifecycle, device types, runtimes, CI automation, keyboard config
• xcresult-parsing.md -- Extracting test results, coverage, failure details, and screenshots from .xcresultbundle
• build-troubleshooting.md -- Common build errors with diagnosis steps and fixes

scripts/

Ready-to-use automation:

• build-and-run.sh -- Build app, install on simulator, launch, capture screenshot
• parse-xcresult.sh -- Extract test results and coverage from .xcresultbundle
• manage-simulators.sh -- Create/boot/reset/delete simulators for testing

assets/templates/

Copy-paste templates:

• xcodebuild-test.sh -- Parameterized test runner with configurable scheme, destination, and result bundle
• SimulatorConfig.json -- Device/OS matrix for multi-device testing (iPhone SE through iPad Pro)

Summary

iOS build verification requires getting the xcodebuild flags, simulator state, and result parsing all correct. A wrong destination string, a missing CODE_SIGNING_ALLOWED flag, or a stale simulator can waste significant time.

This skill eliminates guesswork:
- Decision trees diagnose what went wrong
- Scripts automate the build-install-screenshot loop
- Templates give you correct starting points for CI
- Troubleshooting guides fix the most common errors

Build it. Run it. Verify it.