@@ -101,6 +101,10 @@ extension RunnerTests {
101101
102102 static let flatInteractiveFallbackBudget : TimeInterval = 1.0
103103
104+ #if AGENT_DEVICE_RUNNER_UNIT_TESTS
105+ // `probeWork` is a unit-test-only seam (see `boundedBlockingSystemAlertSnapshot` below): it
106+ // exists only under `AGENT_DEVICE_RUNNER_UNIT_TESTS` so a test can substitute the probe body
107+ // while still calling this exact entry point. Production never compiles this overload.
104108 func snapshotFast (
105109 app : XCUIApplication ,
106110 options : SnapshotOptions ,
@@ -118,6 +122,21 @@ extension RunnerTests {
118122 deadline : deadline
119123 )
120124 }
125+ #else
126+ func snapshotFast ( app : XCUIApplication , options : SnapshotOptions ) throws -> DataPayload {
127+ let deadline = Date ( ) . addingTimeInterval ( Self . snapshotPlanBudget )
128+ if let blocking = boundedBlockingSystemAlertSnapshot ( deadline : deadline ) {
129+ return blocking
130+ }
131+ return try runSnapshotCapturePlan (
132+ Self . regularVisiblePlan ,
133+ app : app ,
134+ options : options ,
135+ terminal : . sparseWithFatalOnAXFailure ,
136+ deadline : deadline
137+ )
138+ }
139+ #endif
121140
122141 func recursiveTreeSnapshotPayload (
123142 context : SnapshotTraversalContext ,
@@ -251,6 +270,9 @@ extension RunnerTests {
251270 )
252271 }
253272
273+ #if AGENT_DEVICE_RUNNER_UNIT_TESTS
274+ // See the `snapshotFast` unit-test seam above: `probeWork` only exists in this
275+ // `AGENT_DEVICE_RUNNER_UNIT_TESTS` build.
254276 func snapshotRaw (
255277 app : XCUIApplication ,
256278 options : SnapshotOptions ,
@@ -268,19 +290,58 @@ extension RunnerTests {
268290 deadline : deadline
269291 )
270292 }
293+ #else
294+ func snapshotRaw ( app : XCUIApplication , options : SnapshotOptions ) throws -> DataPayload {
295+ let deadline = Date ( ) . addingTimeInterval ( Self . snapshotPlanBudget )
296+ if let blocking = boundedBlockingSystemAlertSnapshot ( deadline : deadline ) {
297+ return blocking
298+ }
299+ return try runSnapshotCapturePlan (
300+ Self . rawDiagnosticPlan ,
301+ app : app ,
302+ options : options ,
303+ terminal : . throwOnAXFailure ,
304+ deadline : deadline
305+ )
306+ }
307+ #endif
271308
309+ #if AGENT_DEVICE_RUNNER_UNIT_TESTS
272310 /// Runs the pre-plan SpringBoard system-modal probe as a bounded capture tier sharing the plan
273311 /// deadline, so a slow alert enumeration cannot bypass the snapshot timeout and stall (#1244).
274312 ///
275- /// `probeWork` exists only as a unit-test seam: production callers (`snapshotFast`/
276- /// `snapshotRaw`) always leave it `nil`, in which case the default below reproduces today's
277- /// exact production body (`self.blockingSystemAlertSnapshot(deadline: probeDeadline)`) run
278- /// through the real bounding/hook machinery. Tests substitute a slow/blocking closure to force
279- /// a real timeout without a live SpringBoard alert, while still exercising the real
280- /// `runMainThreadWork` wrap and the real `onAbandoned`/`onDrained` hooks below .
313+ /// `probeWork` exists only as a unit-test seam under `AGENT_DEVICE_RUNNER_UNIT_TESTS`:
314+ /// production (the `#else` overload below) never compiles this parameter. When a test passes
315+ /// `probeWork`, it substitutes a slow/blocking closure to force a real timeout without a live
316+ /// SpringBoard alert, while `boundedBlockingSystemAlertSnapshotBody` still runs the real
317+ /// `runMainThreadWork` wrap and the real `onAbandoned`/`onDrained` hooks — the shared body below
318+ /// is the only place that machinery is defined, so a revert there fails both builds .
281319 func boundedBlockingSystemAlertSnapshot (
282320 deadline : Date ,
283321 probeWork : ( ( ) -> DataPayload ? ) ? = nil
322+ ) -> DataPayload ? {
323+ boundedBlockingSystemAlertSnapshotBody ( deadline : deadline ) { probeDeadline in
324+ probeWork ? ( ) ?? self . blockingSystemAlertSnapshot ( deadline : probeDeadline )
325+ }
326+ }
327+ #else
328+ /// Runs the pre-plan SpringBoard system-modal probe as a bounded capture tier sharing the plan
329+ /// deadline, so a slow alert enumeration cannot bypass the snapshot timeout and stall (#1244).
330+ func boundedBlockingSystemAlertSnapshot ( deadline : Date ) -> DataPayload ? {
331+ boundedBlockingSystemAlertSnapshotBody ( deadline : deadline ) { probeDeadline in
332+ self . blockingSystemAlertSnapshot ( deadline : probeDeadline )
333+ }
334+ }
335+ #endif
336+
337+ /// The real bounding/hook machinery shared by both `boundedBlockingSystemAlertSnapshot`
338+ /// overloads above: the production one (always `self.blockingSystemAlertSnapshot`) and the
339+ /// unit-test one (an injectable `probeWork`). Keeping this in one place means the
340+ /// `runMainThreadWork` wrap and the `onAbandoned`/`onDrained` hooks can never drift between what
341+ /// production runs and what the unit tests exercise.
342+ private func boundedBlockingSystemAlertSnapshotBody (
343+ deadline : Date ,
344+ probe : @escaping ( Date ) -> DataPayload ?
284345 ) -> DataPayload ? {
285346 #if os( macOS )
286347 return nil
@@ -295,7 +356,6 @@ extension RunnerTests {
295356 }
296357 let probeDeadline = Date ( ) . addingTimeInterval ( slice )
297358 let startedAt = Date ( )
298- let work = probeWork ?? { self . blockingSystemAlertSnapshot ( deadline : probeDeadline ) }
299359 do {
300360 return try runMainThreadWork (
301361 command : nil ,
@@ -320,7 +380,7 @@ extension RunnerTests {
320380 NSLog ( " AGENT_DEVICE_RUNNER_SYSTEM_MODAL_PROBE_DRAINED " )
321381 }
322382 ) {
323- work ( )
383+ probe ( probeDeadline )
324384 }
325385 } catch {
326386 NSLog (
@@ -574,16 +634,26 @@ extension RunnerTests {
574634 XCTAssertEqual ( Self . systemModalProbeSlice ( budget : 4 , deadlineRemaining : - 5 ) , 0 )
575635 }
576636
577- /// Regression for #1244/#1248: drives the bounded system-modal probe through `snapshotFast` —
578- /// the real command entry point, not `boundedBlockingSystemAlertSnapshot` directly — with an
579- /// injected `probeWork` that blocks past the probe's real slice, forcing a real
580- /// `runMainThreadWork` timeout. This is revert-sensitive on both halves of the fix:
581- /// - if `snapshotFast` reverted to calling the unbounded `blockingSystemAlertSnapshot`
637+ /// Regression for #1244/#1248: drives the bounded system-modal probe through a real command
638+ /// entry point (`snapshotFast` or `snapshotRaw` -- see the two test methods below), not
639+ /// `boundedBlockingSystemAlertSnapshot` directly, with an injected `probeWork` that blocks past
640+ /// the probe's real slice, forcing a real `runMainThreadWork` timeout. This is revert-sensitive
641+ /// on both halves of the fix, for either entry point:
642+ /// - if the entry point reverted to calling the unbounded `blockingSystemAlertSnapshot`
582643 /// directly (or dropped the `runMainThreadWork` wrap), nothing here would ever time out,
583644 /// so the mid-flight busy/penalty assertions below would never be met;
584645 /// - if the `onAbandoned`/`onDrained` retain/release hooks were dropped, the timeout would
585646 /// still fire, but the busy/penalty accounting and the drain assertion would not hold.
586- func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain ( ) {
647+ ///
648+ /// The drain assertion is synchronized on the *real* release rather than raced: after
649+ /// signaling the probe to finish, the background queue polls `hasAbandonedTreeCapture()`
650+ /// (bounded) and only then fulfills `drained`, which the test `wait(for:timeout:)`s on before
651+ /// asserting `.idle`/`hasAbandonedTreeCapture() == false` below -- so a slow drain fails that
652+ /// assertion instead of racing a fixed-timing guess.
653+ private func assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain (
654+ entryPointName : String ,
655+ callEntryPoint : @escaping ( SnapshotOptions , ( ( ) -> DataPayload ? ) ? ) throws -> DataPayload
656+ ) {
587657 currentApp = springboard
588658 currentBundleId = Self . springboardBundleId
589659 defer {
@@ -608,17 +678,17 @@ extension RunnerTests {
608678 }
609679
610680 let completion = expectation (
611- description : " snapshotFast recovered while the probe was abandoned, then released it"
681+ description : " \( entryPointName ) recovered while the probe was abandoned, then released it "
612682 )
683+ let drained = expectation ( description : " \( entryPointName ) modal probe drained " )
613684 DispatchQueue ( label : " agent-device.runner.tests.modal-probe-timeout " ) . async {
614- box . payload = try? self . snapshotFast (
615- app : self . springboard ,
616- options : SnapshotOptions ( interactiveOnly : false , depth : nil , scope : nil , raw : false ) ,
617- probeWork : probeWork
685+ box . payload = try? callEntryPoint (
686+ SnapshotOptions ( interactiveOnly : false , depth : nil , scope : nil , raw : false ) ,
687+ probeWork
618688 )
619689
620- // 1) Penalty/busy accounting: must already be in place by the time snapshotFast returns,
621- // well before we release the still-blocked probe below.
690+ // 1) Penalty/busy accounting: must already be in place by the time the entry point
691+ // returns, well before we release the still-blocked probe below.
622692 if case . busy = self . currentMainThreadBusyState ( ) {
623693 box . wasBusyBeforeDrain = true
624694 }
@@ -628,27 +698,66 @@ extension RunnerTests {
628698 // 2) `box.payload` above was already produced -- through the capture plan's recovery
629699 // tiers -- while the probe is still blocked on `probeReleaseGate`, i.e. recovered before
630700 // drain, not queued behind it.
701+ completion . fulfill ( )
631702
632- // 3) Only now let the abandoned probe finish and drain.
703+ // 3) Only now let the abandoned probe finish, then block this queue (never the test's
704+ // main-thread wait) on the *real* drain signal -- `onDrained`'s
705+ // `releaseAbandonedXCTestChannelWork` -- bounded so a revert that never drains fulfills
706+ // `drained` anyway and lets the assertions below report the regression explicitly instead
707+ // of just timing out.
633708 probeReleaseGate . signal ( )
634- completion . fulfill ( )
709+ let drainDeadline = Date ( ) . addingTimeInterval ( 5 )
710+ while self . hasAbandonedTreeCapture ( ) , Date ( ) < drainDeadline {
711+ self . sleepFor ( 0.002 )
712+ }
713+ drained . fulfill ( )
635714 }
636715
637716 wait ( for : [ completion ] , timeout : 15 )
638717
639718 // 1) Penalty/busy accounting.
640- XCTAssertTrue ( box . wasBusyBeforeDrain , " expected RUNNER_BUSY while the modal probe timeout is outstanding " )
641- XCTAssertTrue ( box . hadAbandonedCaptureBeforeDrain , " onAbandoned must retain the abandoned XCTest channel work " )
642- XCTAssertTrue ( box . wasPenalizedBeforeDrain , " a timed-out modal probe must penalize the XCTest snapshot channel " )
719+ XCTAssertTrue (
720+ box . wasBusyBeforeDrain ,
721+ " expected RUNNER_BUSY while the \( entryPointName ) modal probe timeout is outstanding "
722+ )
723+ XCTAssertTrue (
724+ box . hadAbandonedCaptureBeforeDrain ,
725+ " onAbandoned must retain the abandoned XCTest channel work for \( entryPointName ) "
726+ )
727+ XCTAssertTrue (
728+ box . wasPenalizedBeforeDrain ,
729+ " a timed-out modal probe must penalize the XCTest snapshot channel for \( entryPointName ) "
730+ )
643731
644732 // 2) Recovered response before drain.
645- XCTAssertNotNil ( box . payload , " snapshotFast must recover a payload through the capture plan while the probe drains " )
733+ XCTAssertNotNil (
734+ box . payload ,
735+ " \( entryPointName ) must recover a payload through the capture plan while the probe drains "
736+ )
646737
647- // 3) Release after drain.
738+ // 3) Bounded, deterministic drain barrier, then release assertions.
739+ wait ( for : [ drained ] , timeout : 6 )
648740 guard case . idle = currentMainThreadBusyState ( ) else {
649- return XCTFail ( " expected the runner to be idle once the abandoned probe drained " )
741+ return XCTFail ( " expected the runner to be idle once the abandoned \( entryPointName ) probe drained " )
742+ }
743+ XCTAssertFalse (
744+ hasAbandonedTreeCapture ( ) ,
745+ " onDrained must release the abandoned XCTest channel work for \( entryPointName ) "
746+ )
747+ }
748+
749+ func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain ( ) {
750+ assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain ( entryPointName : " snapshotFast " ) {
751+ options , probeWork in
752+ try self . snapshotFast ( app : self . springboard , options : options , probeWork : probeWork )
753+ }
754+ }
755+
756+ func testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw ( ) {
757+ assertBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain ( entryPointName : " snapshotRaw " ) {
758+ options , probeWork in
759+ try self . snapshotRaw ( app : self . springboard , options : options , probeWork : probeWork )
650760 }
651- XCTAssertFalse ( hasAbandonedTreeCapture ( ) , " onDrained must release the abandoned XCTest channel work " )
652761 }
653762
654763 func testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied ( ) {
0 commit comments