Reproducible iOS Location Tests with simctl

Features such as delivery address selection, store service-area checks, and geofence alerts often pass with a few taps on a development machine, only to fail intermittently in an unattended pipeline. The problem is usually not the location algorithm. Instead, the simulator has retained coordinates or permissions from a previous job, or a route is still running. To make location tests reproducible on a cloud Mac, treat location as test input that must be explicitly created and destroyed—not as background simulator state.

Separate the Three Test Layers

Do not make a single UI test responsible for coordinate calculations, system location integration, and interface assertions. A more reliable design separates testing into three layers:

Use standard unit tests to verify distances, regions, and state transitions by passing in constructed coordinates directly.
Use a small number of simulator tests to confirm that system location data reaches the app and opens the expected screen.
Use physical devices to validate background wake-ups, signal drift, power consumption, and sensor-dependent behavior.

Start by defining a narrow input boundary for the business layer. For example, have the location service expose only coordinates, timestamps, and authorization status. Do not scatter geofence checks throughout view controllers. This approach lets you cover most boundary conditions without launching a simulator; only the system integration layer needs simctl location.

Simulated coordinates can prove how an app handles a given location. They cannot prove that a real wireless environment will deliver location events at the same cadence.

Create an Isolated Simulator for Every Job

First, select a fixed Xcode path, then list the device types and runtimes actually installed on the machine. Do not permanently hard-code the runtime identifier from an example, because it may change after an Xcode upgrade.

sudo xcode-select -s /Applications/Xcode.app
xcrun simctl list devicetypes
xcrun simctl list runtimes

The pipeline should create an isolated CoreSimulator device set and save the generated UDID for the current job. Replace the device type and runtime identifiers below with values returned by the preceding commands.

set -euo pipefail

DEVICE_SET="$PWD/.simulator-location-tests"
DEVICE_TYPE="com.apple.CoreSimulator.SimDeviceType.iPhone-16"
RUNTIME="com.apple.CoreSimulator.SimRuntime.iOS-18-0"

rm -rf "$DEVICE_SET"
UDID="$(xcrun simctl --set "$DEVICE_SET" create GeoTest "$DEVICE_TYPE" "$RUNTIME")"
xcrun simctl --set "$DEVICE_SET" boot "$UDID"
xcrun simctl --set "$DEVICE_SET" bootstatus "$UDID" -b

An isolated device set is easier to troubleshoot than repeatedly erasing shared simulators. You can temporarily retain the device directory for a failed job and delete it immediately after a successful one. Parallel jobs also avoid competing for the same booted device.

Inject Fixed Coordinates and Permissions

Fixed coordinates are useful for deterministic conditions such as “inside the region,” “crossing the boundary,” and “far from the target.” Install the app, preconfigure permissions, and set the coordinates before launching the test target. If permissions change only after the app starts, the initial screen may already have recorded an unauthorized state.

BUNDLE_ID="com.example.LocationDemo"

xcrun simctl --set "$DEVICE_SET" privacy "$UDID" grant location "$BUNDLE_ID"
xcrun simctl --set "$DEVICE_SET" location "$UDID" set 1.290270,103.851959

xcodebuild test \
  -workspace LocationDemo.xcworkspace \
  -scheme LocationDemo \
  -destination "platform=iOS Simulator,id=$UDID" \
  -resultBundlePath "$PWD/TestResults/LocationTests.xcresult"

Do not test a boundary with only one point. Prepare at least three coordinate sets: one inside the region, one near the boundary, and one outside. Test data should state the expected outcome instead of hiding its meaning behind names such as case1 and case2.

Scenario	Input design	Recommended assertion
Inside the region	Distance from the center is clearly below the threshold	State remains consistently inside the region
Near the boundary	Place one point on each side of the threshold	Comparison rules and rounding are consistent
Outside the region	Distance from the center is clearly above the threshold	No inside-region action is triggered
Permission disabled	Revoke location authorization	Show a recoverable guidance state

If the app caches its last known location, clear app data before each test case or disable persistent caching through test launch arguments. Otherwise, an old value may override the new coordinates.

Validate Movement Order with GPX

Use short, readable GPX files for continuous movement. Keep only the waypoints needed to trigger important state transitions rather than copying an entire real-world route. The following file moves from outside the region to inside it:

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="location-ci">
  <wpt lat="1.320000" lon="103.820000">
    <name>outside</name>
  </wpt>
  <wpt lat="1.290270" lon="103.851959">
    <name>inside</name>
  </wpt>
</gpx>

When running the route, base assertions on event order rather than wait times measured to the exact second.

xcrun simctl --set "$DEVICE_SET" location "$UDID" start "$PWD/Fixtures/enter-region.gpx"
xcodebuild test \
  -workspace LocationDemo.xcworkspace \
  -scheme LocationRouteTests \
  -destination "platform=iOS Simulator,id=$UDID"
xcrun simctl --set "$DEVICE_SET" location "$UDID" stop

The app can record a redacted state sequence such as outside → approaching → inside, with a monotonically increasing timestamp attached to each transition. Do not write complete coordinates to long-term logs. For failure evidence, retain only the test case name, expected region, actual state, and coordinates rounded to a limited number of decimal places.

Clean Up State and Preserve Failure Evidence

Cleanup must not run only on the success path. Register an exit handler as soon as the script starts so that it stops the route, clears the location, and shuts down the device. Decide whether to delete the device set based on the test result.

cleanup() {
  xcrun simctl --set "$DEVICE_SET" location "$UDID" stop 2>/dev/null || true
  xcrun simctl --set "$DEVICE_SET" location "$UDID" clear 2>/dev/null || true
  xcrun simctl --set "$DEVICE_SET" shutdown "$UDID" 2>/dev/null || true
}
trap cleanup EXIT

On failure, archive the xcresult, app logs, the GPX file used, device and runtime identifiers, and the permission state from before the test began. Screenshots can support diagnosis, but they cannot replace structured assertions. If the same coordinates repeatedly fail, first verify that the device set is genuinely isolated, the Bundle ID is correct, and permissions were granted before launch. Only then investigate the business calculations.

A reliable location-testing pipeline should ultimately provide readable test inputs, single-use simulator state, routes that always stop, and business logic that can be unit-tested independently of system location services. When a failure occurs, the team then sees a specific state difference instead of an irreproducible report that “location is sometimes inaccurate.”

Frequently asked questions

Can simctl location injection replace testing on physical devices?

No. It is effective for application state transitions, UI, and business rules, but background delivery, real signal drift, power use, and sensor behavior still require physical-device testing.

Why does a location test pass alone but fail in the full CI suite?

A shared simulator often retains a previous coordinate, permission, or active GPX route. Use a device set per job and explicitly reset location and permission state before and after execution.

When should a test use a fixed coordinate instead of a GPX route?

Use fixed coordinates for deterministic region and boundary assertions. Use GPX routes for movement order and state transitions, without asserting an arrival time accurate to the second.