@@ -15,6 +15,50 @@ const swiftModelsPath = path.resolve(
1515 here ,
1616 '../../../../../apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift' ,
1717) ;
18+ const swiftStatePinPath = path . resolve (
19+ here ,
20+ '../../../../../apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift' ,
21+ ) ;
22+
23+ /**
24+ * One live `assertDecoderPins(…)` call in the native XCTest. Anchored to the start of a line so a
25+ * commented-out or documented call cannot stand in for a pin, and capturing the Swift case as well as
26+ * the decoder name so a pin that pairs the two wrongly is caught here, not only on a lane.
27+ */
28+ const NATIVE_STATE_PIN = / ^ [ \t ] * a s s e r t D e c o d e r P i n s \( \. ( \w + ) , n a m e : " ( \w + ) " , r a w : ( \d + ) \) / gm;
29+
30+ /** The XCTest-discoverable method those pins live in; a `func` without the `test` prefix never runs. */
31+ const NATIVE_TEST_METHOD = / ^ [ \t ] * f u n c t e s t \w * \( \) / m;
32+
33+ /**
34+ * SDK states the decode table omits on purpose: the runner skips `activate()` there, so it stamps no
35+ * fact and the contract declares no prior state for them.
36+ */
37+ const SDK_STATES_THE_DECODER_OMITS = new Set ( [ 'runningForeground' ] ) ;
38+
39+ /** One raw value as the native XCTest pins it. */
40+ type NativeStatePin = Readonly < { sdkCase : string ; name : string ; raw : number } > ;
41+
42+ /**
43+ * The pins the native XCTest writes, taken from its test method onward: a pin above the method that
44+ * runs it is dead code, and a pin that no longer looks like this line is one this tie can no longer
45+ * read — which the caller's coverage assertion reports rather than passing quietly.
46+ */
47+ function readNativeStatePins ( swift : string , file : string ) : NativeStatePin [ ] {
48+ const methodStart = swift . search ( NATIVE_TEST_METHOD ) ;
49+ assert . notEqual (
50+ methodStart ,
51+ - 1 ,
52+ `${ file } must keep a func test… method: XCTest discovers no other` ,
53+ ) ;
54+ return [ ...swift . slice ( methodStart ) . matchAll ( NATIVE_STATE_PIN ) ] . map (
55+ ( [ , sdkCase , name , raw ] ) : NativeStatePin => ( {
56+ sdkCase : sdkCase as string ,
57+ name : name as string ,
58+ raw : Number ( raw ) ,
59+ } ) ,
60+ ) ;
61+ }
1862
1963/**
2064 * The decode table is declared by raw value rather than by position, which buys safety against a
@@ -34,14 +78,57 @@ test('every declared prior state is reachable from some raw value', () => {
3478 ) ;
3579} ) ;
3680
37- test ( 'target activation fact decodes every reason the runner can stamp' , ( ) => {
81+ /**
82+ * `XCUIApplication.h` declares the enum this table names: unknown 0, notRunning 1,
83+ * runningBackgroundSuspended 2, runningBackground 3, runningForeground 4. #2726 is the record of what
84+ * a handwritten copy of that declaration costs — raw 2 and 3 were reversed, so every suspended
85+ * repair was reported as an ordinary background one. The native XCTest pins the same integers against
86+ * the SDK enum; the tie below is what makes the two copies one claim.
87+ */
88+ test ( 'each prior state is named by the raw value the SDK declares' , ( ) => {
89+ assert . deepEqual ( readTargetActivationFact ( wire ( 'stale_target' , 0 ) ) , {
90+ reason : 'stale_target' ,
91+ priorState : 'unknown' ,
92+ } ) ;
93+ assert . deepEqual ( readTargetActivationFact ( wire ( 'bundle_changed' , 1 ) ) , {
94+ reason : 'bundle_changed' ,
95+ priorState : 'notRunning' ,
96+ } ) ;
3897 assert . deepEqual ( readTargetActivationFact ( wire ( 'stale_target' , 2 ) ) , {
98+ reason : 'stale_target' ,
99+ priorState : 'runningBackgroundSuspended' ,
100+ } ) ;
101+ assert . deepEqual ( readTargetActivationFact ( wire ( 'interaction_foreground_guard' , 3 ) ) , {
102+ reason : 'interaction_foreground_guard' ,
103+ priorState : 'runningBackground' ,
104+ } ) ;
105+ } ) ;
106+
107+ /**
108+ * The runner reads `.runningForeground` and skips `activate()`, so raw 4 reaches this decoder only
109+ * from a runner that mis-stamped. The state degrades to `unknown` and the gap is named: inventing a
110+ * prior state the runner never observed is the fabrication the decoder refuses by design.
111+ */
112+ test ( 'the foreground raw value the runner never stamps names no prior state' , ( ) => {
113+ const unmapped : UnmappedPriorStateDetail [ ] = [ ] ;
114+ assert . deepEqual (
115+ readTargetActivationFact ( wire ( 'stale_target' , 4 ) , ( detail ) => unmapped . push ( detail ) ) ,
116+ {
117+ reason : 'stale_target' ,
118+ priorState : 'unknown' ,
119+ } ,
120+ ) ;
121+ assert . deepEqual ( unmapped , [ { reason : 'stale_target' , rawPriorState : 4 } ] ) ;
122+ } ) ;
123+
124+ test ( 'target activation fact decodes every reason the runner can stamp' , ( ) => {
125+ assert . deepEqual ( readTargetActivationFact ( wire ( 'stale_target' , 3 ) ) , {
39126 reason : 'stale_target' ,
40127 priorState : 'runningBackground' ,
41128 } ) ;
42129 assert . deepEqual (
43130 readTargetActivationFact (
44- wire ( 'interaction_foreground_guard' , 3 , { otherActiveApplicationPid : 4562 } ) ,
131+ wire ( 'interaction_foreground_guard' , 2 , { otherActiveApplicationPid : 4562 } ) ,
45132 ) ,
46133 {
47134 reason : 'interaction_foreground_guard' ,
@@ -62,7 +149,7 @@ test('target activation fact decodes every reason the runner can stamp', () => {
62149test ( 'target activation fact omits a foreground pid the runner could not isolate' , ( ) => {
63150 for ( const otherActiveApplicationPid of [ undefined , 0 , - 1 , 4.5 , '4562' , null ] ) {
64151 const decoded = readTargetActivationFact (
65- wire ( 'stale_target' , 2 , { otherActiveApplicationPid : otherActiveApplicationPid as unknown } ) ,
152+ wire ( 'stale_target' , 3 , { otherActiveApplicationPid : otherActiveApplicationPid as unknown } ) ,
66153 ) ;
67154 assert . ok ( decoded ) ;
68155 assert . equal ( 'otherActiveApplicationPid' in decoded , false , String ( otherActiveApplicationPid ) ) ;
@@ -71,7 +158,7 @@ test('target activation fact omits a foreground pid the runner could not isolate
71158
72159test ( 'target activation fact refuses a reason the runner never stamps' , ( ) => {
73160 // A reason the shared rules cannot name is not this repair at all, so nothing is decoded.
74- assert . equal ( readTargetActivationFact ( wire ( 'auto_rebound' , 2 ) ) , undefined ) ;
161+ assert . equal ( readTargetActivationFact ( wire ( 'auto_rebound' , 3 ) ) , undefined ) ;
75162 assert . equal ( readTargetActivationFact ( wire ( 'stale_target' , 'runningBackground' ) ) , undefined ) ;
76163 assert . equal ( readTargetActivationFact ( wire ( 'stale_target' , undefined ) ) , undefined ) ;
77164 assert . equal ( readTargetActivationFact ( undefined ) , undefined ) ;
@@ -81,13 +168,13 @@ test('target activation fact refuses a reason the runner never stamps', () => {
81168} ) ;
82169
83170/**
84- * `XCApplicationState` ships in no public header this repo compiles against, so a raw value the
85- * table never declared must degrade the STATE and keep the disclosure: the reason already proves
86- * `activate()` ran, and the silent repair is the failure #2682 is about. The gap is named in the log.
171+ * A raw value no declaration names must degrade the STATE and keep the disclosure: the reason already
172+ * proves `activate()` ran, and the silent repair is the failure #2682 is about. The gap is named in
173+ * the log.
87174 */
88175test ( 'an unmapped prior-state raw value discloses the repair as unknown and says so' , ( ) => {
89176 const unmapped : UnmappedPriorStateDetail [ ] = [ ] ;
90- for ( const rawPriorState of [ 4 , 99 ] ) {
177+ for ( const rawPriorState of [ 5 , 99 ] ) {
91178 assert . deepEqual ( readTargetActivationFact ( wire ( 'bundle_changed' , rawPriorState ) ) , {
92179 reason : 'bundle_changed' ,
93180 priorState : 'unknown' ,
@@ -96,10 +183,60 @@ test('an unmapped prior-state raw value discloses the repair as unknown and says
96183 readTargetActivationFact ( wire ( 'stale_target' , 42 ) , ( detail ) => unmapped . push ( detail ) ) ;
97184 assert . deepEqual ( unmapped , [ { reason : 'stale_target' , rawPriorState : 42 } ] ) ;
98185 // A mapped value owes no note.
99- readTargetActivationFact ( wire ( 'stale_target' , 2 ) , ( detail ) => unmapped . push ( detail ) ) ;
186+ readTargetActivationFact ( wire ( 'stale_target' , 3 ) , ( detail ) => unmapped . push ( detail ) ) ;
100187 assert . equal ( unmapped . length , 1 ) ;
101188} ) ;
102189
190+ /**
191+ * The kernel's declared list promises `XCApplicationState` raw order. Only the decoder assigns raw
192+ * values, so the decoder is what proves that promise — and an unmapped raw is the callback's job, not
193+ * a state the list can be ordered by.
194+ */
195+ test ( 'the declared prior-state list follows the SDK raw order' , ( ) => {
196+ const unmapped : UnmappedPriorStateDetail [ ] = [ ] ;
197+ const ordered : string [ ] = [ ] ;
198+ for ( let raw = 0 ; raw < 16 ; raw ++ ) {
199+ const unmappedBefore = unmapped . length ;
200+ const fact = readTargetActivationFact ( wire ( 'stale_target' , raw ) , ( detail ) =>
201+ unmapped . push ( detail ) ,
202+ ) ;
203+ if ( fact && unmapped . length === unmappedBefore ) ordered . push ( fact . priorState ) ;
204+ }
205+ assert . deepEqual ( ordered , [ ...IOS_TARGET_ACTIVATION_PRIOR_STATES ] ) ;
206+ } ) ;
207+
208+ /**
209+ * Two handwritten copies of an Apple enum is how #2726 happened. The native XCTest compares each raw
210+ * value against `XCUIApplication.State` itself, on the lanes whose SDK declares the case; this reads
211+ * those pins back from source, so the decode table and the pins agree on every host and every lane
212+ * without a device. Neither half alone is enough: this test cannot see the SDK, and the macOS build
213+ * compiles the suspended case out.
214+ */
215+ test ( 'the decode table matches the raw values the native XCTest pins from the SDK enum' , ( ) => {
216+ const pins = readNativeStatePins (
217+ fs . readFileSync ( swiftStatePinPath , 'utf8' ) ,
218+ path . basename ( swiftStatePinPath ) ,
219+ ) ;
220+ const mismatches : string [ ] = [ ] ;
221+ for ( const { sdkCase, name, raw } of pins ) {
222+ if ( sdkCase !== name ) mismatches . push ( `.${ sdkCase } is pinned under the name ${ name } ` ) ;
223+ const decoded = readTargetActivationFact ( wire ( 'stale_target' , raw ) ) ?. priorState ;
224+ const expected = SDK_STATES_THE_DECODER_OMITS . has ( name ) ? 'unknown' : name ;
225+ if ( decoded !== expected )
226+ mismatches . push ( `raw ${ raw } : decoder says ${ decoded } , SDK pins ${ name } ` ) ;
227+ }
228+ assert . deepEqual ( mismatches , [ ] ) ;
229+ // A pin this scan can no longer read — renamed call, wrapped line, deleted case — would leave the
230+ // table unchecked against the SDK again, so every declared state has to show up here.
231+ assert . deepEqual (
232+ IOS_TARGET_ACTIVATION_PRIOR_STATES . filter ( ( state ) => ! pins . some ( ( pin ) => pin . name === state ) ) ,
233+ [ ] ,
234+ `every declared prior state must stay pinned by a live assertDecoderPins line in ${ path . basename (
235+ swiftStatePinPath ,
236+ ) } `,
237+ ) ;
238+ } ) ;
239+
103240test ( 'wire key matches the runner payload property that carries it' , ( ) => {
104241 const swift = fs . readFileSync ( swiftModelsPath , 'utf8' ) ;
105242 assert . match (
0 commit comments