watchOS XCUITest spike¶
The watchOS runner is an XCUITest service-style test on the watchOS simulator. It supports hierarchy, tap and screenshot operations; these are its capabilities and limits.
Clock face and Smart Stack driver¶
- The runner’s
facecommand targetscom.apple.clockfacefor normalized taps, 0.1-second press-and-drag gestures, directional swipes and text dumps. - The Smart Stack widget driver (
scripts/watch/addSmartStackWidget.ts) uses a calibrated gallery position (steps from the bottom, default one) and the first widget preview. After the gallery swipe settles, a dump checks for the exactAppGroupCell -- <appName>identifier. When gallery rows are readable but the app row is missing, the driver searches by scrolling later, then earlier, settling 1500 ms before each dump. Each direction stops at an unchanged row set, no rows, or eight steps. - The driver taps a row found by scrolling at its visible centre normalized by the window size, followed by the first widget preview and add taps. Rows with less than 24 pt visible need another scroll within the cap. The driver nudges rows covered by the picker’s navigation bar earlier before tapping. A row in the initial dump preserves the calibrated flow.
- If the search misses and another attempt remains, with
--udid <simulator UDID>the host relaunches clockface usingxcrun simctl terminate <udid> com.apple.clockface. It waits 3000 ms for respawn and retries withinmaxAttemptswithout the retry delay. The final attempt skips relaunch and its wait. Without a relaunch dependency it stops with that command as recovery guidance. An initial dump with no gallery row identifiers preserves the calibrated flow. The result’sgalleryRowMissescounts missing-row attempts. - App and widget display names verify the resulting cell identifier. When the face leaves both
name fields empty, a cell verifies when its host bundle id and widget kind equal
hostBundleIdandwidgetKind(--host-bundle-id,--widget-kind, given together). Otherwise it verifies only as the one cell added since that attempt’s header dump whose labels hold the app name. That means every earlier cell id is still present and the count is up by exactly one. - Before each edit the driver checks the header dump. A cell that already matches returns
success with
alreadyPresent: trueand adds nothing. On a retry, so does the one nameless cell added since the first attempt’s header dump, so a retry after a missed readback adds no duplicate. - Home is lossy and non-idempotent, so opening the stack allows three home/swipe-up rounds. Each round polls twice after its first swipe; if the header and Edit button are not visible, it sends up to three more swipes, polling twice after each.
- Cell verification allows ten dumps. Failed verification retries the whole flow up to
maxAttempts(default 3, range 1–5;--attempts). It waitsretryDelayMsbetween attempts (default 20000 ms, integer range 0–120000;--retry-delay-ms) for gallery indexing after installation. Polls settle 250 ms between dumps. Header failures, errors and cancellation stop the flow. A successful gesture alone does not establish widget presence. - The script drives the runner WebSocket and makes no daemon tool call. With
--session-uuidit therefore holds that one-shot CLI session like a--cliinvocation. It claims the session’s liveness under its own owner token. It declares acliidle window covering the session’s idle age plus twice the base window. The idle age comes fromdaemon/sessionInfo’slastUsedAt, so a session an earlier hold kept is not cut short. The script refreshes the window every quarter window and leaves the session at least the base window after the run (one-hour daemon cap).
Capability boundary¶
| Check | Result | Evidence and limits |
|---|---|---|
| Launch | Yes | xcodebuild test-without-building with platform=watchOS Simulator runs the service-style test. |
| Socket | Yes | A runner NWListener on port 4199 exchanges ping/pong with the host over shared loopback. TEST_RUNNER_AM_PORT=4199 arrives as AM_PORT; SIMCTL_CHILD_* was not tested. |
| Hierarchy | Yes | snapshot() returns frames, labels, identifiers, and element types. debugDescription also works. |
| Tap and press | Yes | Element tap, coordinate tap, and coordinate press(forDuration:) each reach the counter button. |
| Drag and swipes | Calls succeed; effect unverified | press(forDuration:thenDragTo:) and all four swipe directions return without error; scroll displacement was not read back. |
| Home | Call succeeds | XCUIDevice.shared.press(.home) returns without error. |
| Digital Crown rotation | Yes, with Crown focus | Typed XCUIDevice IMP calls change the focused view’s bound Crown value. This does not demonstrate scrolling a real ScrollView. |
| Screenshots | Yes | XCUIScreen.main.screenshot() and simctl io screenshot both work. |
| System apps | Settings yes; Carousel no | com.apple.NanoSettings activates and snapshots. Launching com.apple.Carousel is rejected by IOSSHLMainWorkspace. |
| CtrlProxy typecheck | Yes, compilation only | Sources/CtrlProxy typechecks with the sdk-wire module and ObjC catcher module map for arm64-apple-watchos10.0-simulator. os(iOS)-gated and UIKit-importing paths are compiled out, so they do not demonstrate watchOS behaviour. CtrlProxy itself was neither built with xcodebuild nor run. |
Installation and runner lifetime¶
For this standalone watch app, Info.plist must contain both WKApplication = true
and WKWatchOnly = true. WKApplication alone fails installation with
MIInstallerErrorDomain 97 because a non-watch-only app requires
WKCompanionAppBundleIdentifier.
Under load, test-without-building can keep running after the test passes; use a hard timeout
wrapper.
Digital Crown contract¶
Rotation reaches the view that holds Crown focus. The demonstrated target uses
.focusable(), an @FocusState set in onAppear, and
.digitalCrownRotation($crown, from: -1000, through: 1000, by: 0.1,
sensitivity: .high, isContinuous: true, isHapticFeedbackEnabled: false).
The test taps the crown text before rotation. An unfocused target and
perform(_:with:) calls with boxed NSNumber arguments did not change the value;
typed @convention(c) IMP calls confirm rotation:
| Private selector | @convention(c) signature |
|---|---|
rotateDigitalCrownByDelta:withVelocity: |
(AnyObject, Selector, Double, Double) -> Void |
rotateDigitalCrownByDelta: |
(AnyObject, Selector, Double) -> Void |
rotateDigitalCrown:velocity: |
(AnyObject, Selector, Double, Double) -> Void (encoding v32@0:8d16d24) |
The app binding’s sensitivity, step, continuous range, and velocity affect the
result, and wrapping or clamping makes the delta-to-value mapping nonlinear. A Crown action must
report the requested delta, not a resulting position. Guard each private
selector with responds(to:) and return a typed unsupported error if absent.
Each call takes seconds, so many small steps exceed a runner timeout. Use one
call per Crown action, with a larger delta as needed and its own timeout. An
enclosing ScrollView without a Crown binding does not move.
The capture at test/fixtures/watchos-xcuitest/hierarchy.json is the original
23-node probe hierarchy, with counter and Crown values at zero. Element types
are XCUIElement.ElementType raw values.
Open gaps¶
- Scrolling a real
ScrollViewby Crown is untested. - The
os(iOS)-gated CtrlProxy input paths need watchOS implementations. - Physical watches and changes to the iOS CtrlProxy test target are out of scope.
Simulator pairing lifecycle¶
startDevice accepts pairWithDeviceId for watchOS. It validates an iOS-runtime simulator,
then pairs and activates under the watch lifecycle lease before boot; it never boots the phone.
Same-phone pairs are adopted (created: false) and activated only if inactive. New pairs are
active on creation; the explicit activation also tolerates NSPOSIXErrorDomain code 37.
A watch can have only one phone: an existing other-phone pair or simctl code 403 refuses with
unpair-or-use-existing-phone guidance. A phone may have several watches.
After watch boot a fresh pair listing supplies state and connection, which may still be disconnected. iOS and watchOS device listings expose pairs best-effort. A process-wide in-memory registry records only daemon-created pair IDs and watch UDIDs. Watch deletion and discard of a watch created by failed provisioning unpair those IDs best-effort before deletion; adopted pairs are never unpaired. Failed unpairs warn and retain the record for retry.