Skip to content

Commit 1f95ea3

Browse files
committed
refactor(ios): declare runner screen-capture facts at the owning contract
#2728 asked for the runner's display facts at the owning cross-language contract, not by per-consumer casts. The wire key was a TypeScript literal and the shape a Swift struct pinned only by two hand-written Swift encode tests, so every consumer restated a shape it did not own. Move the read to packages/contracts/src/screen-capture-contract.ts and record the wire key plus two measured Duo poses in the golden table contracts/fixtures/screen-capture-metadata.json. The table names no field of its own: this module's reader and ScreenshotMetadataPayload stay the only two declarations of the shape, and each language decodes the table through its own, so a renamed or dropped fact fails both lanes. The vitest twin asserts the host reads exactly the facts a capture recorded and refuses anything that cannot describe one. Negative control on a booted iPhone Duo: renaming pixelsPerPoint in the table alone turns both lanes red, Swift with DecodingError.keyNotFound at captures[0].metadata and vitest by refusing the payload.
1 parent ca2970b commit 1f95ea3

6 files changed

Lines changed: 248 additions & 131 deletions

File tree

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+AppScreenCaptureTests.swift‎

Lines changed: 57 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,37 @@
11
import XCTest
22

33
#if AGENT_DEVICE_RUNNER_UNIT_TESTS
4+
/// One read of contracts/fixtures/screen-capture-metadata.json. The capture decodes through the
5+
/// production `ScreenshotMetadataPayload`, so the table cannot describe a shape this encoder does
6+
/// not write, and this file's re-encode cannot write a shape the table does not describe. The table
7+
/// names no field of its own: this struct and the host's reader in
8+
/// `packages/contracts/src/screen-capture-contract.ts` are the only declarations of the shape, and
9+
/// `packages/contracts/src/screen-capture-contract.test.ts` is the vitest twin (#2728).
10+
private struct ScreenCaptureMetadataTable: Decodable {
11+
struct Capture: Decodable {
12+
let name: String
13+
let metadata: ScreenshotMetadataPayload
14+
}
15+
16+
let key: String
17+
let captures: [Capture]
18+
}
19+
20+
private func loadScreenCaptureMetadataTable() throws -> ScreenCaptureMetadataTable {
21+
let fixtureURL = URL(fileURLWithPath: #filePath)
22+
.deletingLastPathComponent() // UnitTests
23+
.deletingLastPathComponent() // AgentDeviceRunnerUITests
24+
.deletingLastPathComponent() // AgentDeviceRunner
25+
.deletingLastPathComponent() // runner
26+
.deletingLastPathComponent() // apple
27+
.deletingLastPathComponent() // repo root
28+
.appendingPathComponent("contracts/fixtures/screen-capture-metadata.json")
29+
return try JSONDecoder().decode(
30+
ScreenCaptureMetadataTable.self,
31+
from: Data(contentsOf: fixtureURL)
32+
)
33+
}
34+
435
extension RunnerTests {
536
func testScreenCaptureFailureCarriesTheBridgeReasonAsItsOwnCode() {
637
XCTAssertEqual(
@@ -26,34 +57,39 @@ extension RunnerTests {
2657
)
2758
}
2859

29-
func testScreenshotResultEncodesDisplayFactsUnderTheKeyTheHostReads() throws {
30-
// The measured open-Duo inner panel: 2852x2006 at scale 3 on display 3. The host reads these to
31-
// rescale an image it did not measure, so the key and the shape are a cross-language contract.
32-
let payload = DataPayload(
33-
message: "tmp/screenshot-1.png",
34-
screenshotMetadata: ScreenshotMetadataPayload(
35-
displayID: 3,
36-
pixelWidth: 2852,
37-
pixelHeight: 2006,
38-
pixelsPerPoint: 3
60+
func testScreenshotDisplayFactsReEncodeEveryGoldenTableRowUnderTheTablesKey() throws {
61+
let table = try loadScreenCaptureMetadataTable()
62+
XCTAssertFalse(table.captures.isEmpty, "the table must record at least one measured capture")
63+
for capture in table.captures {
64+
let payload = DataPayload(
65+
message: "tmp/screenshot-1.png",
66+
screenshotMetadata: capture.metadata
3967
)
40-
)
41-
let encoded = try JSONSerialization.jsonObject(
42-
with: JSONEncoder().encode(payload)
43-
) as? [String: Any]
44-
XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png")
45-
let metadata = encoded?["screenshotMetadata"] as? [String: Any]
46-
XCTAssertEqual(metadata?["displayID"] as? UInt, 3)
47-
XCTAssertEqual(metadata?["pixelWidth"] as? Int, 2852)
48-
XCTAssertEqual(metadata?["pixelHeight"] as? Int, 2006)
49-
XCTAssertEqual(metadata?["pixelsPerPoint"] as? Double, 3)
68+
let encoded = try JSONSerialization.jsonObject(
69+
with: JSONEncoder().encode(payload)
70+
) as? [String: Any]
71+
XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png", capture.name)
72+
// The host reads these facts under the key the table spells, which neither language restates.
73+
guard let metadata = encoded?[table.key] as? [String: Any] else {
74+
return XCTFail("\(capture.name): no display facts under the table's key '\(table.key)'")
75+
}
76+
XCTAssertEqual(metadata["displayID"] as? UInt, capture.metadata.displayID, capture.name)
77+
XCTAssertEqual(metadata["pixelWidth"] as? Int, capture.metadata.pixelWidth, capture.name)
78+
XCTAssertEqual(metadata["pixelHeight"] as? Int, capture.metadata.pixelHeight, capture.name)
79+
XCTAssertEqual(
80+
metadata["pixelsPerPoint"] as? Double,
81+
capture.metadata.pixelsPerPoint,
82+
capture.name
83+
)
84+
}
5085
}
5186

5287
func testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved() throws {
88+
let key = try loadScreenCaptureMetadataTable().key
5389
let encoded = try JSONSerialization.jsonObject(
5490
with: JSONEncoder().encode(DataPayload(message: "tmp/screenshot-1.png"))
5591
) as? [String: Any]
56-
XCTAssertNil(encoded?["screenshotMetadata"])
92+
XCTAssertNil(encoded?[key], "a capture that resolved nothing owes no facts either")
5793
}
5894
}
5995
#endif
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"comment": "Cross-language golden table for the display facts one Apple runner capture reports about the image it encoded (#2728). The vitest twin is packages/contracts/src/screen-capture-contract.test.ts and the Swift twin is UnitTests/RunnerTests+AppScreenCaptureTests.swift, which decodes and re-encodes every capture through the production ScreenshotMetadataPayload — so a renamed or dropped fact fails both lanes. This table deliberately records no field list: the Swift struct and the TypeScript reader are the only declarations of the shape. Add a measured capture here, never to one suite.",
3+
"key": "screenshotMetadata",
4+
"captures": [
5+
{
6+
"name": "Open Duo, resolved inner panel LCD-1: the window is 951x669 pt on display 3 and the upright encoding is one pixel per axis under the 2853x2007 CoreDevice calls the panel",
7+
"metadata": {
8+
"displayID": 3,
9+
"pixelWidth": 2852,
10+
"pixelHeight": 2006,
11+
"pixelsPerPoint": 3
12+
}
13+
},
14+
{
15+
"name": "Closed Duo, outer panel LCD: the same command following the app onto the other panel, reported by the window that moved with it",
16+
"metadata": {
17+
"displayID": 1,
18+
"pixelWidth": 1398,
19+
"pixelHeight": 2034,
20+
"pixelsPerPoint": 3
21+
}
22+
}
23+
]
24+
}
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { test } from 'vitest';
2+
import assert from 'node:assert/strict';
3+
import fs from 'node:fs';
4+
import path from 'node:path';
5+
import {
6+
readRunnerScreenCaptureMetadata,
7+
type RunnerScreenCaptureMetadata,
8+
} from './screen-capture-contract.ts';
9+
10+
// Cross-language golden table: the display facts a runner capture reports about its own image are
11+
// written by the Swift encoder (`ScreenshotMetadataPayload`) and read here. Every capture in
12+
// contracts/fixtures/screen-capture-metadata.json is asserted by this file AND by
13+
// `UnitTests/RunnerTests+AppScreenCaptureTests.swift`, which decodes and re-encodes each one through
14+
// the production struct, so a renamed or dropped fact turns both suites red without a simulator. The
15+
// table names no field of its own: the two production types are the only declarations of the shape.
16+
type ScreenCaptureMetadataTable = {
17+
key: string;
18+
captures: Array<{ name: string; metadata: RunnerScreenCaptureMetadata }>;
19+
};
20+
21+
const TABLE = JSON.parse(
22+
fs.readFileSync(
23+
path.resolve(
24+
import.meta.dirname,
25+
'..',
26+
'..',
27+
'..',
28+
'contracts',
29+
'fixtures',
30+
'screen-capture-metadata.json',
31+
),
32+
'utf8',
33+
),
34+
) as ScreenCaptureMetadataTable;
35+
36+
const [MEASURED] = TABLE.captures;
37+
assert(MEASURED, 'the golden table must record at least one measured capture');
38+
39+
/** A runner `data` payload, as the native side answers a file-path screenshot. */
40+
function runnerPayload(metadata: unknown): Record<string, unknown> {
41+
return { message: 'tmp/screenshot-1.png', [TABLE.key]: metadata };
42+
}
43+
44+
test('reads every measured capture the golden table records', () => {
45+
for (const capture of TABLE.captures) {
46+
// deepEqual pins the key set as well as the values, so a reader that gained or renamed a fact
47+
// stops matching the capture the encoder produced.
48+
assert.deepEqual(
49+
readRunnerScreenCaptureMetadata(runnerPayload(capture.metadata)),
50+
capture.metadata,
51+
capture.name,
52+
);
53+
}
54+
});
55+
56+
test('refuses a payload missing any fact the golden table records', () => {
57+
for (const field of Object.keys(MEASURED.metadata)) {
58+
const partial: Record<string, number> = { ...MEASURED.metadata };
59+
delete partial[field];
60+
assert.equal(
61+
readRunnerScreenCaptureMetadata(runnerPayload(partial)),
62+
undefined,
63+
`missing ${field}`,
64+
);
65+
}
66+
});
67+
68+
test('reports no source fact when the runner carried no metadata', () => {
69+
assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
70+
});
71+
72+
test.each([
73+
['a non-object payload', 'not-an-object'],
74+
['an array payload', [MEASURED.metadata]],
75+
['the pre-panel scale probe leaking in as zero', { ...MEASURED.metadata, displayID: 0 }],
76+
['a zero-scale image', { ...MEASURED.metadata, pixelsPerPoint: 0 }],
77+
['a non-integer pixel box', { ...MEASURED.metadata, pixelWidth: 2852.5 }],
78+
['a negative scale', { ...MEASURED.metadata, pixelsPerPoint: -3 }],
79+
['a non-numeric scale', { ...MEASURED.metadata, pixelsPerPoint: '3' }],
80+
])('refuses %s rather than guessing a capture', (_case, metadata) => {
81+
assert.equal(readRunnerScreenCaptureMetadata(runnerPayload(metadata)), undefined);
82+
});
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
/**
2+
* The display facts an Apple runner capture reports about the image it encoded (#2728).
3+
*
4+
* A foldable lights one panel at a time and the dark panel still answers with a valid all-black PNG
5+
* at exit zero, so a capture has to carry its own proof of what it looked at: the display it
6+
* captured, the box it encoded, and how many pixels make one point. Swift owns the encoder
7+
* (`ScreenshotMetadataPayload` in `RunnerTests+Models.swift`) and this module owns the reader; those
8+
* two types are the only declarations of the shape. The golden table
9+
* `contracts/fixtures/screen-capture-metadata.json` carries the wire key and two real measured
10+
* captures, and each language decodes it through its own production type — this file's test and
11+
* `UnitTests/RunnerTests+AppScreenCaptureTests.swift` — so a renamed or dropped fact turns both
12+
* lanes red without a simulator. A consumer may not restate this shape as a local literal or read it
13+
* through an unchecked cast.
14+
*/
15+
16+
/** The `data` key a runner screenshot result carries its display facts under. */
17+
const RUNNER_SCREEN_CAPTURE_METADATA_KEY = 'screenshotMetadata';
18+
19+
/**
20+
* What one runner capture measured about itself. `pixelsPerPoint` is the scale of the image the
21+
* runner encoded, `pixelWidth`/`pixelHeight` are that encoded image's own box after the runner drew
22+
* it upright, and `displayID` is the screen the window reported — never a screen chosen by number
23+
* or by position in a screen list.
24+
*/
25+
export type RunnerScreenCaptureMetadata = Readonly<{
26+
displayID: number;
27+
pixelWidth: number;
28+
pixelHeight: number;
29+
pixelsPerPoint: number;
30+
}>;
31+
32+
/**
33+
* Reads the display facts out of a runner `data` payload. Returns undefined when the payload carries
34+
* none or carries a value that cannot describe a real capture, which leaves the consumer with no
35+
* source fact — the honest pre-panel state — rather than a number invented from a panel nobody
36+
* measured. The Swift encoder refuses to report a scale that is not finite and positive, so these
37+
* refusals are the host's defence against a payload that did not come from that encoder.
38+
*/
39+
export function readRunnerScreenCaptureMetadata(
40+
data: Record<string, unknown>,
41+
): RunnerScreenCaptureMetadata | undefined {
42+
const raw = data[RUNNER_SCREEN_CAPTURE_METADATA_KEY];
43+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
44+
const payload = raw as Record<string, unknown>;
45+
const displayID = readPositiveInteger(payload.displayID);
46+
const pixelWidth = readPositiveInteger(payload.pixelWidth);
47+
const pixelHeight = readPositiveInteger(payload.pixelHeight);
48+
const pixelsPerPoint = readPositiveFinite(payload.pixelsPerPoint);
49+
if (
50+
displayID === undefined ||
51+
pixelWidth === undefined ||
52+
pixelHeight === undefined ||
53+
pixelsPerPoint === undefined
54+
) {
55+
return undefined;
56+
}
57+
return Object.freeze({ displayID, pixelWidth, pixelHeight, pixelsPerPoint });
58+
}
59+
60+
function readPositiveInteger(value: unknown): number | undefined {
61+
return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
62+
}
63+
64+
function readPositiveFinite(value: unknown): number | undefined {
65+
return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
66+
}

‎packages/platform-apple/src/core/__tests__/screenshot.test.ts‎

Lines changed: 15 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
import { beforeEach, test, vi } from 'vitest';
22
import assert from 'node:assert/strict';
3-
import { promises as fs } from 'node:fs';
3+
import { promises as fs, readFileSync } from 'node:fs';
44
import path from 'node:path';
5+
import type { RunnerScreenCaptureMetadata } from '@agent-device/contracts/screen-capture-contract';
56
import { mkdtempForTest } from '../../__tests__/tmp-dir.ts';
67

78
vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
@@ -49,7 +50,6 @@ import {
4950
captureSimulatorScreenshotWithFallback,
5051
captureSimulatorScreenshotWithRetry,
5152
captureScreenshotViaRunner,
52-
readRunnerScreenCaptureMetadata,
5353
resolveSimulatorRunnerScreenshotCandidatePaths,
5454
shouldRetryIosSimulatorScreenshot,
5555
} from '../screenshot.ts';
@@ -70,6 +70,17 @@ const mockEnsureBootedSimulator = vi.mocked(ensureBootedSimulator);
7070
const mockOpenIosSimulatorApp = vi.mocked(openIosSimulatorApp);
7171
const mockPrepareStatusBarForScreenshot = vi.mocked(prepareSimulatorStatusBarForScreenshot);
7272

73+
// The wire key and a real measured capture come from the cross-language golden table, so this
74+
// consumer suite cannot spell a shape the Swift encoder disagrees with (#2728).
75+
const SCREEN_CAPTURE_TABLE = JSON.parse(
76+
readFileSync(
77+
new URL('../../../../../contracts/fixtures/screen-capture-metadata.json', import.meta.url),
78+
'utf8',
79+
),
80+
) as { key: string; captures: Array<{ metadata: RunnerScreenCaptureMetadata }> };
81+
const [MEASURED_CAPTURE] = SCREEN_CAPTURE_TABLE.captures;
82+
assert(MEASURED_CAPTURE, 'the golden table must record at least one measured capture');
83+
7384
beforeEach(() => {
7485
vi.resetAllMocks();
7586
mockRunCmd.mockImplementation(execActual.runCmd);
@@ -505,7 +516,7 @@ test('captureScreenshotViaRunner reports the display facts a runner capture meas
505516
await fs.writeFile(runnerImage, 'runner-image', 'utf8');
506517
mockRunAppleRunnerCommand.mockResolvedValue({
507518
message: 'tmp/duo.png',
508-
screenshotMetadata: { displayID: 3, pixelWidth: 2852, pixelHeight: 2006, pixelsPerPoint: 3 },
519+
[SCREEN_CAPTURE_TABLE.key]: MEASURED_CAPTURE.metadata,
509520
});
510521
mockRunCmd.mockImplementation(async (_cmd, args) => {
511522
if (args.includes('get_app_container')) {
@@ -517,12 +528,7 @@ test('captureScreenshotViaRunner reports the display facts a runner capture meas
517528
try {
518529
const outPath = path.join(tmpDir, 'out.png');
519530
const metadata = await captureScreenshotViaRunner(device, outPath);
520-
assert.deepEqual(metadata, {
521-
displayID: 3,
522-
pixelWidth: 2852,
523-
pixelHeight: 2006,
524-
pixelsPerPoint: 3,
525-
});
531+
assert.deepEqual(metadata, MEASURED_CAPTURE.metadata);
526532
assert.equal(await fs.readFile(outPath, 'utf8'), 'runner-image');
527533
} finally {
528534
await fs.rm(tmpDir, { recursive: true, force: true });
@@ -568,52 +574,3 @@ test('captureScreenshotViaRunner copies macOS runner screenshots from the host',
568574
await fs.rm(tmpDir, { recursive: true, force: true });
569575
}
570576
});
571-
572-
// The open-Duo row of the #2727 measurement: a resolved inner panel reports 2852x2006 at scale 3,
573-
// one pixel per axis smaller than the size CoreDevice calls the panel.
574-
const OPEN_DUO_CAPTURE = {
575-
displayID: 3,
576-
pixelWidth: 2852,
577-
pixelHeight: 2006,
578-
pixelsPerPoint: 3,
579-
};
580-
581-
// The wire key is spelled as a literal because the Swift encoder, not this module, owns it (#2728).
582-
function runnerCapturePayload(metadata: unknown): Record<string, unknown> {
583-
return { message: 'tmp/screenshot-1.png', screenshotMetadata: metadata };
584-
}
585-
586-
test('reads the display facts a resolved runner capture reported', () => {
587-
assert.deepEqual(
588-
readRunnerScreenCaptureMetadata(runnerCapturePayload(OPEN_DUO_CAPTURE)),
589-
OPEN_DUO_CAPTURE,
590-
);
591-
assert.deepEqual(
592-
readRunnerScreenCaptureMetadata(
593-
runnerCapturePayload({
594-
displayID: 1,
595-
pixelWidth: 1398,
596-
pixelHeight: 2034,
597-
pixelsPerPoint: 3,
598-
}),
599-
),
600-
{ displayID: 1, pixelWidth: 1398, pixelHeight: 2034, pixelsPerPoint: 3 },
601-
);
602-
});
603-
604-
test('reports no source fact when the runner carried no metadata', () => {
605-
assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
606-
});
607-
608-
test.each([
609-
['a non-object payload', 'not-an-object'],
610-
['an array payload', [OPEN_DUO_CAPTURE]],
611-
['the pre-panel scale probe value leaking in as zero', { ...OPEN_DUO_CAPTURE, displayID: 0 }],
612-
['a zero-scale image', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: 0 }],
613-
['a non-integer pixel box', { ...OPEN_DUO_CAPTURE, pixelWidth: 2852.5 }],
614-
['a missing side', { displayID: 3, pixelWidth: 2852, pixelsPerPoint: 3 }],
615-
['a negative scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: -3 }],
616-
['a non-numeric scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: '3' }],
617-
])('refuses %s rather than guessing a capture scale', (_case, metadata) => {
618-
assert.equal(readRunnerScreenCaptureMetadata(runnerCapturePayload(metadata)), undefined);
619-
});

0 commit comments

Comments
 (0)