gui/docs/using-ios.md

iOS Native Development Tips

Running Detox Tests

Metro Setup

Run Metro separately for faster iteration:

cd code/kitchen-sink
bun run start > /tmp/metro.log 2>&1 &

Then run detox with --reuse to use existing Metro:

npx detox test -c ios.sim.debug --reuse

Single Test Workflow (Recommended for Dev)

For one-off test runs, use --maxWorkers 1 to avoid spawning multiple simulators:

# run a single test on one simulator (fast iteration)
npx detox test -c ios.sim.debug --reuse --retries 0 --maxWorkers 1 -t "test name"

This prevents Detox from launching 10+ simulators in parallel, which is noisy for debugging.

Full Test Suite (CI or Final Verification)

For running all tests, omit --maxWorkers to use parallelization:

npx detox test -c ios.sim.debug --reuse

Useful Detox Flags

• --retries 0 - fail fast, don't retry
• -t "test name" - run specific test by name
• --reuse - use existing metro/app (faster iteration)
• --maxWorkers 1 - single simulator (quieter for debugging)
• --headless - run without simulator UI (CI only)

Example:

npx detox test -c ios.sim.debug --reuse --retries 0 --maxWorkers 1 -t "sheet drag test"

Managing Simulators

Detox can leave many simulators running. Here's how to manage them:

# list all simulators
xcrun simctl list devices

# shutdown all simulators
xcrun simctl shutdown all

# boot a specific simulator
xcrun simctl boot "iPhone 15"

# erase a simulator (fresh state)
xcrun simctl erase "iPhone 15"

# delete unavailable simulators (cleanup old Xcode versions)
xcrun simctl delete unavailable

If simulators are stuck in "Shutting Down" state:

# force kill all simulator processes
killall Simulator 2>/dev/null
xcrun simctl shutdown all
sleep 2
xcrun simctl boot "iPhone 15"

Debugging Workflow

1. Skip tests already verified to speed up cycles
2. Use console.warn() (not console.log) in native code to see output in metro
3. Filter metro logs: grep -E "pattern" /tmp/metro.log
4. Take screenshots in tests: await device.takeScreenshot('name')
5. Check screenshots in e2e/artifacts/ after runs

Example

The keyboard tests verify smooth handoff between keyboard and sheet gestures:

# Run keyboard-specific tests
detox test --reuse --retries 0 -t "Keyboard"

# Watch for keyboard events in metro logs
grep -E "keyboard|Keyboard|kb-" /tmp/metro.log