Key checks
Work through the guide
Start with the section that matches your task, then follow the evidence and recovery steps before calling the test complete.
Layer 1: make coordinate logic deterministic
Distance thresholds, geofence classification, nearest-store ranking, route parsing, and coordinate formatting do not need a changing device location. Pass known CLLocation or CLLocationCoordinate2D values into the logic and assert the result. This keeps the fastest tests independent of radios, permissions, network state, and the place where the test machine happens to be.
Include boundary values, not only happy paths. Test a point just inside and just outside a radius, longitude near the antimeridian if your product is global, invalid latitude and longitude, missing accuracy, old timestamps, and two coordinates that display the same rounded text but differ at full precision.
- Keep coordinate math outside CLLocationManager delegates.
- Store canonical latitude and longitude at sufficient precision.
- Assert both the classification and the evidence shown to a user.
- Use fixtures named for the behavior, not only for a city.
Layer 2: control location in test plans and UI automation
Apple test plans can set a simulated location for tests. For UI automation, Apple documents setting XCUIDevice.shared.location to an XCUILocation because the app under UI test runs in a separate process. This distinction matters: a setting that affects the test bundle is not automatically evidence that the separately launched app saw the same value.
A strong UI test records the location input, launches into a known permission and account state, waits for the app's own location-loading boundary, and asserts the final screen. When the app calls a backend, also record a test-safe server assertion so a green label is not the only proof.
- Use one named location per behavioral assertion.
- Reset permissions, account fixtures, and cached selections deliberately.
- Wait on an application state instead of a fixed delay.
- Capture a screenshot and diagnostics only when they help explain failure.
Layer 3: use GPX for movement, not a pile of static cities
A GPX journey is appropriate when speed, course, waypoint timing, enter and exit events, or map-camera following matter. It is not necessary for a pricing screen that only branches by one region. Matching the fixture to the behavior keeps tests easier to debug.
Design routes to expose one boundary at a time. A short route crossing one geofence edge is more useful than a long city tour when the assertion is duplicate entry events. Include a stop or slow segment when the app reacts to dwell time, and end with an explicit clear or neutral state so a later test cannot inherit motion.
- Name the expected boundary and direction of travel.
- Keep route speed and timestamps realistic for the feature.
- Assert event order as well as event count.
- Stop the journey and verify cleanup.
Layer 4: close the Simulator-to-device gap
Simulator is excellent for fast coverage, but Apple notes that simulated devices do not reproduce every physical-device characteristic. A final device pass is appropriate when permissions, background behavior, location-source interaction, network profiles, app cache, or customer-visible recovery affect the result.
On a device you own or are authorized to test, WLOC can save the target, parse a map link, prepare the compatible setup path, show diagnostic timestamps, and guide recovery. The target app still decides how to combine iOS permissions, cached state, GPS or other inputs, account rules, and server logic. Write the acceptance criterion around observed behavior, not around the marketing name of a tool.
- Confirm the test build, account, and backend environment.
- Use a public low-risk point for the first device check.
- Record the newest request, result, app state, and timestamp.
- Clear routes and static targets, then prove normal behavior returned.
Decision table
Developer location tool selection
Choose the cheapest layer that can produce trustworthy evidence for the behavior under test.
| Behavior to verify | Preferred tool | Evidence to keep |
|---|---|---|
| Distance, radius, or coordinate parsing | Unit test with constructed coordinates | Inputs, expected classification, assertion output |
| A screen driven by one known location | Xcode test plan or XCUILocation | Fixture name, app state, UI assertion |
| Movement, course, speed, or geofence transitions | GPX journey | Route version, event order, entry and exit results |
| Exploratory location states | Simulator location controls | Reproduction notes and app diagnostics |
| Authorized physical-device integration | WLOC plus the compatible test environment | Target, request/result timestamps, target-app proof, recovery |
| Live third-party service behavior | Service-approved test method | Written authorization and service-specific evidence |
Practical playbook
A release-ready location test run
This sequence keeps failures attributable and makes the final recovery state part of the test rather than an afterthought.
- 1Define one observable contractWrite the input, build, account, backend, permission state, expected output, and allowed tolerance before changing a location.
- 2Prove the lowest layer firstRun coordinate and business-logic tests before UI, GPX, Simulator, or device work so math failures are not misdiagnosed as location-delivery failures.
- 3Run one controlled integrationUse a named test location, capture the newest request and app result, and compare both with the expected product state.
- 4Exercise a negative or boundary caseTest permission denied, a point just outside the geofence, stale cache, or a missing network response so the fallback is also known.
- 5Restore and re-readStop motion, clear static targets, reopen or refresh as required, and record proof that the real or pass-through state is current.
References
Verify the claims in this guide
Open the references below for the platform documentation, service policies, and product boundaries used in the guide.
Simulating location in tests
Test-plan locations, GPX replay, constructed coordinates, and XCUILocation.
Open the source ↗Improving tests with test plans
How simulated location belongs to a repeatable test-plan configuration.
Open the source ↗Testing complex hardware scenarios in Simulator
Preset routes, custom coordinates, and clearing a Simulator location.
Open the source ↗isSimulatedBySoftware
The source-information signal Apple exposes for software-simulated locations.
Open the source ↗FAQ
Developer location · iPhone testing FAQ
Can Xcode simulate a route instead of one location?
Yes. Apple documents adding a GPX file to a test plan so Xcode can replay a journey with location, elevation, and velocity changes.
Why does a UI test need XCUILocation?
Apple explains that UI automation launches the app in a separate process, so the test-plan setting for the test bundle is not the same path. XCUILocation supplies the UI-test device location.
Should I test only in Simulator?
No. Simulator is efficient for broad coverage, but a physical-device pass is appropriate for hardware interaction, permissions, background behavior, caching, and real integration boundaries.
Is WLOC a replacement for XCTest?
No. XCTest, Swift Testing, test plans, GPX, and Simulator should cover source-controlled behavior. WLOC helps with repeatable coordinate and device-workflow evidence in a compatible authorized scope.
What is the minimum recovery proof?
Show that no route or static target remains, obtain a new pass-through or normal-location result, and confirm the target app no longer displays the previous test state.