iOS Native Development Tips

Running Detox Tests

Metro Setup

Run Metro separately for faster iteration:

bash

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

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

bash

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:

bash

# 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:

bash

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:

bash

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:

bash

# 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:

bash

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

Debugging Workflow

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

Example

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

bash

# 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