Skip to content

tvOS: every snapshot/alert resolution fails because the runner probes com.apple.springboard (no SpringBoard on tvOS) #1351

Description

@svatopluknovak

This is an issue I encountered when trying to use agent-device on tvOS (simulator). All the info below is AI-generated.

Summary

On tvOS, every snapshot and alert resolution fails. The bundled XCTest
runner probes com.apple.springboard for blocking system modals on each
snapshot/alert resolution, but tvOS has no SpringBoard (it uses PineBoard /
HeadBoard). The query raises an XCTest failure that safely() cannot catch
(it only catches Obj-C exceptions), so the whole runner test dies. The CLI
then misreports this as:

the current screen is overwhelming the iOS accessibility capture

which sends you looking in the wrong direction entirely.

Environment

  • agent-device: 0.19.3 (reproduces on all ≤ 0.19.3)
  • Platform: tvOS Simulator — Apple TV 4K (3rd gen), tvOS 26.2 (23K51)
  • Host: macOS (Darwin), Apple Silicon

Steps to reproduce

  1. Boot a tvOS simulator.
  2. agent-device open <bundle-id> --platform apple --target tv --session appletv
    (--target tv selects the tvOS/TV-class target on the Apple backend;
    --platform ios --target tv behaves identically.)
  3. agent-device snapshot -i --session appletv
  4. Snapshot fails; CLI reports the screen as "overwhelming the accessibility capture".

Actual signature

~/.agent-device/sessions/<session>/runner.log shows:
RunnerTests+SystemModal.swift:74: error: … Failed to resolve query: Application com.apple.springboard is not running

Root cause

Two places in the runner assume a SpringBoard-style app exists:

  • apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift
    blockingSystemAlertSnapshot() is compiled for tvOS but queries
    com.apple.springboard, which never runs there.
  • apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift
    resolveAlert(app:) (#if !os(macOS)) hits the same path.
    Because the failure is an XCTest assertion (not an Obj-C exception),
    safely() does not trap it and the runner test terminates.

Suggested fix

Guard the SpringBoard probe so it does not run on tvOS. A minimal fix mirrors
the existing macOS guards:

  • RunnerTests+SystemModal.swift — in blockingSystemAlertSnapshot()
    change #if os(macOS)#if os(macOS) || os(tvOS)
  • RunnerTests+Alert.swift — in resolveAlert(app:)
    change #if !os(macOS)#if !os(macOS) && !os(tvOS)
    A more complete fix would probe the correct tvOS system UI host
    (PineBoard / HeadBoard) instead of skipping the check, so system-modal
    handling still works on tvOS.

Workaround (verified working)

Patching the two files above in the installed package and clearing the runner
build cache resolves it:
rm -rf ~/.agent-device/apple-runner/derived/tvos-simulator

This has to be re-applied after every agent-device update, which is why we'd
love an upstream fix.

Secondary issue

The user-facing error ("the current screen is overwhelming the iOS
accessibility capture") is misleading for this failure mode — a runner test
that terminated on an uncaught XCTest assertion should surface differently
from a genuinely too-heavy screen.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions