tvOS XCUITest spike¶
The tvOS runner is an XCUITest service-style test on the Apple TV simulator. These are the runner capabilities and limits it builds on.
Capability boundary¶
| Check | Result | Evidence and limits |
|---|---|---|
| Launch | Yes | xcodebuild test-without-building with platform=tvOS Simulator runs the service-style test. TvosRunnerArtifacts selects an explicit override, local products, or a checksum-verified release archive before building from source. |
| Socket | Yes | A runner NWListener on port 4189 accepts a host loopback connection and exchanges ping/pong. TEST_RUNNER_AM_PORT=4189 on the xcodebuild command arrives as AM_PORT. SIMCTL_CHILD_* was not tested. |
| Hierarchy with focus | Yes | snapshot() returns frames, labels, identifiers, element types, hasFocus, isEnabled, and isSelected, including for com.apple.TVSettings. |
| Remote | Yes | XCUIRemote.shared.press(_:) handles up, down, left, right, select, menu, home, and play/pause; press(.select, forDuration: 1.5) works. Focus is visible in the next snapshot after the press returns. |
| Direct focus targeting | No | XCUIElement does not respond to focus, setHasFocus:, or requestFocus. Directional moves reach the geometric neighbour from known grid cells, but focus memory changes subsequent destinations. |
| Text | Yes | Selecting the focused field opens the full-screen keyboard, with Keyboard focused. app.typeText("hello") sets the field value to hello. |
| Screenshots | Yes | XCUIScreen.main.screenshot() and simctl io screenshot both work. |
| CtrlProxy typecheck | Yes, compilation only | Sources/CtrlProxy typechecks with the sdk-wire module and ObjC catcher module map for arm64-apple-tvos17.0-simulator. os(iOS)-gated and UIKit-importing paths are compiled out and provide no tvOS behaviour. CtrlProxy itself was neither built with xcodebuild nor run. |
Focus and runner constraints¶
- Reaching an element takes a path of directional remote moves, with a fresh focus read after
every move. The focus engine remembers the last item per column: moving up from the text field
after leaving
B22returns toB22, not the geometricB21. So neither grid geometry nor a previously planned path predicts focus. - Settings (
com.apple.TVSettings) supports system-app hierarchy capture. Activatingcom.apple.TVWatchListandcom.apple.TVHomeScreenfails; they are not usable capture targets. - Under load a test invocation can keep running after the test passes: use a hard timeout and read results from test logs or result files.
test/fixtures/tvos-xcuitest/focus-hierarchy.jsonis the probe hierarchy (text field focused at launch). Element types areXCUIElement.ElementTyperaw values.- Physical Apple TV is out of scope; tvOS 27 and Duo-style runtimes were not covered by the spike.