Skip to content

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 face command targets com.apple.clockface for 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 exact AppGroupCell -- <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 using xcrun simctl terminate <udid> com.apple.clockface. It waits 3000 ms for respawn and retries within maxAttempts without 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’s galleryRowMisses counts 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 hostBundleId and widgetKind (--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: true and 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 waits retryDelayMs between 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-uuid it therefore holds that one-shot CLI session like a --cli invocation. It claims the session’s liveness under its own owner token. It declares a cli idle window covering the session’s idle age plus twice the base window. The idle age comes from daemon/sessionInfo’s lastUsedAt, 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 ScrollView by 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.

Background