Add trigger-screenshot command to simulate iOS screenshot notification #123

Problem

There is currently no way to programmatically trigger iOS's UIApplication.userDidTakeScreenshotNotification through agent-device. The existing screenshot command captures a screenshot image to a file (via xcrun simctl io screenshot), but it does not fire the in-app screenshot notification that iOS apps can observe.

Many iOS apps use this notification to trigger in-app behavior — for example, bug reporters, feedback tools, or annotation overlays that activate when a user takes a screenshot. Without the ability to trigger this notification, these workflows cannot be automated through agent-device.

What we tried

• xcrun simctl io booted screenshot — captures image only, no notification
• xcrun simctl spawn booted notifyutil -p "com.apple.UIKit.userDidTakeScreenshot" — posts a Darwin notification, but UIApplication.userDidTakeScreenshotNotification is a Cocoa NotificationCenter notification, not a Darwin notification, so apps don't receive it
• Various other Darwin notification names (com.apple.springboard.screenshot.taken, etc.) — none trigger the in-app notification
• xcrun simctl addmedia — adds to Photos but doesn't trigger screenshot detection

The fundamental issue is that UIApplication.userDidTakeScreenshotNotification is posted by UIKit internally within the app process when SpringBoard notifies it through a private IPC channel. It cannot be triggered from outside the process via simctl or Darwin notifications.

Proposed Solution

Add a new trigger-screenshot command that posts UIApplication.userDidTakeScreenshotNotification from within the XCTest runner process. Since the runner runs inside the simulator, and NotificationCenter.default notifications are delivered across all apps in the simulator environment, this should cause any app observing the notification to react — just as if the user had pressed the hardware screenshot buttons.

Implementation outline

1. Swift XCTest Runner (RunnerTests.swift)

Add a new triggerScreenshot case to CommandType and handle it in executeOnMain:

case .triggerScreenshot:
    NotificationCenter.default.post(
        name: UIApplication.userDidTakeScreenshotNotification,
        object: nil
    )
    return Response(ok: true, data: DataPayload(message: "screenshot notification triggered"))

2. TypeScript dispatch (src/core/dispatch.ts)

Add a 'trigger-screenshot' case that routes through the XCTest runner client.

3. Capabilities (src/core/capabilities.ts)

Register as iOS simulator-only:

'trigger-screenshot': { ios: { simulator: true } },

CLI usage

agent-device trigger-screenshot

This would pair naturally with the existing screenshot command:

• screenshot — capture a screenshot image to a file
• trigger-screenshot — simulate the user taking a screenshot (fires notification without saving an image)

Use Case

We're building automated testing for an iOS app that uses screenshot detection to trigger a bug reporter. The bug reporter listens for UIApplication.userDidTakeScreenshotNotification and presents a form when detected. We want to automate the full flow: trigger the bug reporter → fill in the form → submit — all through agent-device.