Skip to content

Commit 2a37022

Browse files
committed
fix(ios-runner): decode targetActivation prior states in the SDK's order
The decoder translated the runner's raw `XCApplicationState` integer with a handwritten table that had `RunningBackgroundSuspended = 2` and `RunningBackground = 3` reversed, so a suspended app was disclosed as merely backgrounded in `targetActivation.priorState` and the appended warning. The runner itself stamps `state.rawValue`, so only this translation was wrong, and it shipped in v0.21.7 and v0.21.8. The table now follows what `XCUIAutomation/XCUIApplication.h` declares, and the claim that these values have no public SDK declaration is gone. `RunnerTests+ApplicationStateRawValueTests.swift` pins every integer against `XCUIApplication.State` itself — with the platform guard the SDK uses for the suspended case — and the decoder test reads those pins back, so the two copies of the enum cannot drift apart unnoticed. The kernel's prior-state list keeps its promised raw order, and the manual lane's expected log pairing says what the corrected decoder answers. Closes #2726
1 parent 6cb160a commit 2a37022

7 files changed

Lines changed: 210 additions & 24 deletions

File tree

‎.device-evidence/CHECKLIST.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,11 @@ already-installed bundle id is not evidence.
5151
`XCUIApplication.activate()` runs, and the fact is stamped only in the branch where `activate()` is
5252
actually called. Assert the pair on the same device run:
5353

54-
- `runner.log`: `AGENT_DEVICE_RUNNER_ACTIVATE_FACT bundle=... reason=... priorState=2
55-
otherActiveApplicationPid=<N>` — the same line's `priorState` is what the response must carry;
56-
`state=` on the preceding `AGENT_DEVICE_RUNNER_ACTIVATE` must be non-foreground.
54+
- `runner.log`: `AGENT_DEVICE_RUNNER_ACTIVATE_FACT bundle=... reason=... priorState=<2|3>
55+
otherActiveApplicationPid=<N>` — the same line's `priorState` is what the response must carry, named
56+
by the raw values the SDK declares: 2 is `runningBackgroundSuspended`, 3 is `runningBackground`
57+
(#2726 — the decoder had these two reversed). `state=` on the preceding
58+
`AGENT_DEVICE_RUNNER_ACTIVATE` must be non-foreground.
5759
- The response can therefore never report `priorState: runningForeground`. Both directions are pinned
5860
in the runner unit lane (`UnitTests/RunnerTests+LifecycleCacheTests.swift`): the already-foreground
5961
call asserts `pendingTargetActivation == nil` and the backgrounded call asserts the stamped

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,13 @@
1313
`hingeAngleDegrees` and the previous reading, and says the hinge was observed half-open and did
1414
not settle rather than claiming it never got there. `fold-pose-unverified` still covers a budget
1515
that ends on another pose. Supersedes ADR 0025's budget-end exception (#2730).
16+
- Fixed (ios): a foreground repair names the state the session app was really in. The decoder translated
17+
the runner's raw `XCApplicationState` integer from a handwritten table that had
18+
`runningBackgroundSuspended` (2) and `runningBackground` (3) the wrong way round, so a suspended app
19+
was disclosed as merely backgrounded in `targetActivation.priorState` and in the appended warning —
20+
as shipped in v0.21.7 and v0.21.8. The table now follows what the SDK declares, a runner XCTest pins
21+
every integer against `XCUIApplication.State` itself, and the decoder test reads those pins, so the
22+
two copies cannot drift apart unnoticed.
1623
- Fixed (macos): `press` and `click` on the `frontmost-app`, `desktop`, and `menubar` surfaces post
1724
clicks the way a trackpad does. The helper posted the release in the same tick as the press, so
1825
AppKit dropped it and controls never activated; each press is now held (`--hold-ms`, 60 ms by
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import XCTest
2+
3+
#if AGENT_DEVICE_RUNNER_UNIT_TESTS
4+
extension RunnerTests {
5+
/// Pins the raw value of every `XCUIApplication.State` the TypeScript decoder names and of the
6+
/// foreground state it omits. Each expectation is compared against the SDK's own enum, never
7+
/// against a second handwritten table: the decoder maps the integer the runner stamps, and #2726
8+
/// shipped `runningBackground` and `runningBackgroundSuspended` reversed.
9+
///
10+
/// The host lane runs this on every PR, and `.github/workflows/ios.yml` lists it for the simulator
11+
/// lane so the suspended case — compiled out of the macOS build below — is pinned on every PR too.
12+
/// `packages/platform-apple/src/runner/__tests__/target-activation.test.ts` reads these calls back
13+
/// and compares them with its decode table, so a table that drifts from them fails on any host
14+
/// instead of waiting for a lane to report a mislabelled repair.
15+
func testApplicationStateRawValuesMatchTheActivationDecoder() {
16+
assertDecoderPins(.unknown, name: "unknown", raw: 0)
17+
assertDecoderPins(.notRunning, name: "notRunning", raw: 1)
18+
#if !os(macOS)
19+
// The SDK declares the suspended state only for non-macOS platforms, so the host lane — which
20+
// compiles this bundle for macOS — has no case to pin and the iOS lanes do.
21+
assertDecoderPins(.runningBackgroundSuspended, name: "runningBackgroundSuspended", raw: 2)
22+
#endif
23+
assertDecoderPins(.runningBackground, name: "runningBackground", raw: 3)
24+
assertDecoderPins(.runningForeground, name: "runningForeground", raw: 4)
25+
}
26+
27+
private func assertDecoderPins(_ state: XCUIApplication.State, name: String, raw: Int) {
28+
XCTAssertEqual(
29+
Int(state.rawValue),
30+
raw,
31+
"XCUIApplication.State \(name) no longer carries the raw value the decoder maps it to (#2726)"
32+
)
33+
}
34+
}
35+
#endif

‎packages/kernel/src/snapshot.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -437,15 +437,17 @@ export function isIosTargetActivationReason(value: unknown): value is IosTargetA
437437
}
438438

439439
/**
440-
* States an activation could have been needed for, in `XCApplicationState` raw order.
441-
* `runningForeground` is excluded because the runner skips `activate()` when the app is already
442-
* foreground and never stamps a fact there.
440+
* States an activation could have been needed for, in `XCApplicationState` raw order: unknown 0,
441+
* notRunning 1, suspended 2, plain background 3 — the SDK declares suspended on non-macOS platforms
442+
* only. `runningForeground` is excluded because the runner skips `activate()` when the app is already
443+
* foreground and never stamps a fact there. The decoder, which assigns raw values, is what keeps this
444+
* order honest.
443445
*/
444446
export const IOS_TARGET_ACTIVATION_PRIOR_STATES = [
445447
'unknown',
446448
'notRunning',
447-
'runningBackground',
448449
'runningBackgroundSuspended',
450+
'runningBackground',
449451
] as const;
450452

451453
export type IosTargetActivationPriorState = (typeof IOS_TARGET_ACTIVATION_PRIOR_STATES)[number];

‎packages/platform-apple/src/__tests__/interactor-target-activation.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ function interactorServing(payload: Record<string, unknown>) {
3636
test('a capture whose own command repaired foreground discloses it and keeps the fact', async () => {
3737
const snapshot = (await interactorServing({
3838
...HEALTHY_TREE,
39-
targetActivation: { reason: 'stale_target', priorState: 2, otherActiveApplicationPid: 4562 },
39+
targetActivation: { reason: 'stale_target', priorState: 3, otherActiveApplicationPid: 4562 },
4040
}).snapshot()) as SnapshotResult;
4141

4242
assert.deepEqual(snapshot.targetActivation, {
@@ -68,7 +68,7 @@ test('an activation fact the runner could not attribute to one app discloses no
6868

6969
assert.deepEqual(snapshot.targetActivation, {
7070
reason: 'interaction_foreground_guard',
71-
priorState: 'runningBackground',
71+
priorState: 'runningBackgroundSuspended',
7272
});
7373
assert.equal(snapshot.warnings?.[0]?.includes('pid'), false);
7474
});

‎packages/platform-apple/src/runner/__tests__/target-activation.test.ts‎

Lines changed: 146 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -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]*assertDecoderPins\(\.(\w+), name: "(\w+)", raw: (\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]*func test\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', () => {
62149
test('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

72159
test('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
*/
88175
test('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+
103240
test('wire key matches the runner payload property that carries it', () => {
104241
const swift = fs.readFileSync(swiftModelsPath, 'utf8');
105242
assert.match(

‎packages/platform-apple/src/runner/target-activation.ts‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,19 @@ export type UnmappedPriorStateDetail = Readonly<{
2222
export const TARGET_ACTIVATION_WIRE_KEY = 'targetActivation';
2323

2424
/**
25-
* `XCApplicationState` raw value → declared state, declared by value and never by array position:
26-
* the enum ships in no public Xcode header this repo compiles against, so a reordering or a new
27-
* case must not silently relabel a repair. `runningForeground` is deliberately absent — the runner
28-
* skips `activate()` there and stamps no fact.
25+
* `XCApplicationState` raw value → declared state, as the SDK's `XCUIAutomation/XCUIApplication.h`
26+
* declares it: `RunningBackgroundSuspended = 2` (non-macOS only) and `RunningBackground = 3`. The
27+
* table is keyed by value rather than by position, and
28+
* `RunnerTests+ApplicationStateRawValueTests.swift` pins these integers against the SDK enum itself,
29+
* because #2726 shipped 2 and 3 reversed and every suspended repair was reported as an ordinary
30+
* background one. `runningForeground` — raw 4 — is deliberately absent: the runner skips `activate()`
31+
* there and stamps no fact.
2932
*/
3033
const PRIOR_STATE_BY_RAW_VALUE: Readonly<Record<number, IosTargetActivationPriorState>> = {
3134
0: 'unknown',
3235
1: 'notRunning',
33-
2: 'runningBackground',
34-
3: 'runningBackgroundSuspended',
36+
2: 'runningBackgroundSuspended',
37+
3: 'runningBackground',
3538
};
3639

3740
export function readTargetActivationFact(

0 commit comments

Comments
 (0)