Run Tests

# Step 1: Run UI tests sequentially
xcodebuild test \
  -scheme <SCHEME> \
  -destination 'platform=iOS Simulator,name=<SIMULATOR>' \
  -only-testing:<UI_TEST_TARGET> \
  -parallel-testing-enabled NO

# Step 2: Run unit tests in parallel
xcodebuild test \
  -scheme <SCHEME> \
  -destination 'platform=iOS Simulator,name=<SIMULATOR>' \
  -skip-testing:<UI_TEST_TARGET> \
  -parallel-testing-enabled YES

Via XcodeBuildMCP:

# UI tests sequential
test_sim({ extraArgs: ["-only-testing:StuffolioUITests", "-parallel-testing-enabled", "NO"] })

# Unit tests parallel
test_sim({ extraArgs: ["-skip-testing:StuffolioUITests", "-parallel-testing-enabled", "YES"] })

Strategy 2: All Sequential

Maximum stability. Use when experiencing any test flakiness.

xcodebuild test \
  -scheme <SCHEME> \
  -destination 'platform=iOS Simulator,name=<SIMULATOR>' \
  -parallel-testing-enabled NO

Via XcodeBuildMCP:

test_sim({ extraArgs: ["-parallel-testing-enabled", "NO"] })

Strategy 3: All Parallel

Fastest execution. Use with clean simulator state or in CI.

xcodebuild test \
  -scheme <SCHEME> \
  -destination 'platform=iOS Simulator,name=<SIMULATOR>' \
  -parallel-testing-enabled YES \
  -maximum-concurrent-test-simulator-destinations 2

Via XcodeBuildMCP:

test_sim({ extraArgs: ["-parallel-testing-enabled", "YES", "-maximum-concurrent-test-simulator-destinations", "2"] })

Time Estimates

Based on Stuffolio (~4,700 total tests, ~195 UI tests):

Why UI tests are slow:

• Each test launches the app fresh (~2-3 sec)
• Simulator animations and delays
• waitForExistence timeouts (up to 3-5 sec each)
• Setup/teardown overhead

Rule of thumb: ~15-30 seconds per UI test when run sequentially.

Pre-Run Cleanup (Optional)

If experiencing clone issues, run cleanup first:

# Kill zombie simulators
xcrun simctl shutdown all
killall Simulator 2>/dev/null

# Delete cloned simulators
xcrun simctl delete unavailable

# Optional: Clean DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/<PROJECT>-*

Unattended Mode

To run tests while away from the computer, use /run-tests --unattended.

What this does:

• Skips the strategy selection prompt (uses Smart Split by default, or specify with --sequential / --parallel)
• Uses XcodeBuildMCP tools which don't require per-command approval
• Runs cleanup, then tests, then reports results

Example invocations:

/run-tests --unattended              # Smart Split (default)
/run-tests --unattended --sequential # All sequential
/run-tests --unattended --parallel   # All parallel
/run-tests --unattended --cleanup    # Run cleanup before tests

Permissions required (approve once before leaving):

Tip: If using --cleanup, approve the Bash permissions once, then Claude will remember for the session.

Workflow

Interactive Mode (default)

1. Ask user which strategy they want (default: Smart Split)
2. Detect the UI test target name from the project
3. Execute using XcodeBuildMCP or xcodebuild
4. Report results with pass/fail counts

Unattended Mode (--unattended)

1. Skip prompts - use specified or default strategy
2. Run cleanup if --cleanup flag present
3. Execute using XcodeBuildMCP (no approval needed)
4. Report results when complete

Auto-Detection

To find the UI test target:

# List schemes and targets
xcodebuild -list -project <PROJECT>.xcodeproj

Common UI test target patterns:

• <AppName>UITests
• <AppName>-UITests
• UITests