Skip to content

Commit 86caa19

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 pin the wire key, the four field names, and two measured Duo poses in the golden table contracts/fixtures/screen-capture-metadata.json. The vitest twin asserts the host reads exactly those facts and no others; the runner lane decodes and re-encodes every row through the production ScreenshotMetadataPayload, so a rename on either side fails on both. 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 15ae636 commit 86caa19

6 files changed

Lines changed: 280 additions & 127 deletions

File tree

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

Lines changed: 59 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -26,34 +26,72 @@ extension RunnerTests {
2626
)
2727
}
2828

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
39-
)
29+
/// Cross-language golden table: the display facts a runner capture reports about its own image are
30+
/// written here and read by the host through
31+
/// `packages/contracts/src/screen-capture-contract.ts`. Every row of
32+
/// contracts/fixtures/screen-capture-metadata.json is decoded and re-encoded through the production
33+
/// `ScreenshotMetadataPayload`, so renaming a field on either side fails this decode, and a field
34+
/// added here cannot reach the wire without the table saying so. The vitest twin is
35+
/// `packages/contracts/src/screen-capture-contract.test.ts` (#2728).
36+
private struct ScreenCaptureMetadataTable: Decodable {
37+
struct Entry: Decodable {
38+
let name: String
39+
let metadata: ScreenshotMetadataPayload
40+
}
41+
42+
let key: String
43+
let fields: [String]
44+
let captures: [Entry]
45+
}
46+
47+
private func loadScreenCaptureMetadataTable() throws -> ScreenCaptureMetadataTable {
48+
let fixtureURL = URL(fileURLWithPath: #filePath)
49+
.deletingLastPathComponent() // UnitTests
50+
.deletingLastPathComponent() // AgentDeviceRunnerUITests
51+
.deletingLastPathComponent() // AgentDeviceRunner
52+
.deletingLastPathComponent() // runner
53+
.deletingLastPathComponent() // apple
54+
.deletingLastPathComponent() // repo root
55+
.appendingPathComponent("contracts/fixtures/screen-capture-metadata.json")
56+
return try JSONDecoder().decode(
57+
ScreenCaptureMetadataTable.self,
58+
from: Data(contentsOf: fixtureURL)
4059
)
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)
60+
}
61+
62+
func testScreenshotDisplayFactsReEncodeEveryGoldenTableRowUnderTheTablesKey() throws {
63+
let table = try loadScreenCaptureMetadataTable()
64+
XCTAssertFalse(table.captures.isEmpty, "the golden table must record at least one measured capture")
65+
for entry in table.captures {
66+
let payload = DataPayload(
67+
message: "tmp/screenshot-1.png",
68+
screenshotMetadata: entry.metadata
69+
)
70+
let encoded = try JSONSerialization.jsonObject(
71+
with: JSONEncoder().encode(payload)
72+
) as? [String: Any]
73+
XCTAssertEqual(encoded?["message"] as? String, "tmp/screenshot-1.png", entry.name)
74+
// The host reads these facts by the key the table spells, which neither language restates.
75+
guard let metadata = encoded?[table.key] as? [String: Any] else {
76+
return XCTFail("\(entry.name): no display facts under the table's key '\(table.key)'")
77+
}
78+
XCTAssertEqual(Set(metadata.keys), Set(table.fields), entry.name)
79+
XCTAssertEqual(metadata["displayID"] as? UInt, entry.metadata.displayID, entry.name)
80+
XCTAssertEqual(metadata["pixelWidth"] as? Int, entry.metadata.pixelWidth, entry.name)
81+
XCTAssertEqual(metadata["pixelHeight"] as? Int, entry.metadata.pixelHeight, entry.name)
82+
XCTAssertEqual(
83+
metadata["pixelsPerPoint"] as? Double,
84+
entry.metadata.pixelsPerPoint,
85+
entry.name
86+
)
87+
}
5088
}
5189

5290
func testScreenshotResultCarriesNoDisplayFactsWhenNothingResolved() throws {
5391
let encoded = try JSONSerialization.jsonObject(
5492
with: JSONEncoder().encode(DataPayload(message: "tmp/screenshot-1.png"))
5593
) as? [String: Any]
56-
XCTAssertNil(encoded?["screenshotMetadata"])
94+
XCTAssertNil(encoded?[try loadScreenCaptureMetadataTable().key])
5795
}
5896
}
5997
#endif
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"comment": "Cross-language wire contract 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 entry through the production ScreenshotMetadataPayload. Add facts here, never to one side.",
3+
"key": "screenshotMetadata",
4+
"fields": ["displayID", "pixelWidth", "pixelHeight", "pixelsPerPoint"],
5+
"captures": [
6+
{
7+
"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",
8+
"metadata": {
9+
"displayID": 3,
10+
"pixelWidth": 2852,
11+
"pixelHeight": 2006,
12+
"pixelsPerPoint": 3
13+
}
14+
},
15+
{
16+
"name": "Closed Duo, outer panel LCD: the same command following the app onto the other panel, reported by the window that moved with it",
17+
"metadata": {
18+
"displayID": 1,
19+
"pixelWidth": 1398,
20+
"pixelHeight": 2034,
21+
"pixelsPerPoint": 3
22+
}
23+
}
24+
]
25+
}
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
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 { readRunnerScreenCaptureMetadata } from './screen-capture-contract.ts';
6+
7+
// Cross-language golden table: the display facts a runner capture reports about its own image are
8+
// written by the Swift encoder (`ScreenshotMetadataPayload`) and read here. Every entry in
9+
// contracts/fixtures/screen-capture-metadata.json is asserted by this file AND by
10+
// `UnitTests/RunnerTests+AppScreenCaptureTests.swift`, which decodes and re-encodes each entry
11+
// through the production struct. Rename a field or the wire key on one side and both suites go red
12+
// without a simulator; add facts to the table, never to one side (#2728).
13+
type ScreenCaptureMetadataTable = {
14+
key: string;
15+
fields: string[];
16+
captures: Array<{
17+
name: string;
18+
metadata: Record<string, number>;
19+
}>;
20+
};
21+
22+
const TABLE_PATH = path.resolve(
23+
import.meta.dirname,
24+
'..',
25+
'..',
26+
'..',
27+
'contracts',
28+
'fixtures',
29+
'screen-capture-metadata.json',
30+
);
31+
32+
function readTable(): ScreenCaptureMetadataTable {
33+
return JSON.parse(fs.readFileSync(TABLE_PATH, 'utf8')) as ScreenCaptureMetadataTable;
34+
}
35+
36+
/** A runner `data` payload as the native side would answer a file-path screenshot. */
37+
function runnerPayload(metadata: unknown, key = readTable().key): Record<string, unknown> {
38+
return { message: 'tmp/screenshot-1.png', [key]: metadata };
39+
}
40+
41+
test('the screen-capture golden table declares a usable wire shape', () => {
42+
const table = readTable();
43+
assert.ok(table.key.length > 0, 'the table must name the key the host reads');
44+
assert.deepEqual(table.fields, ['displayID', 'pixelWidth', 'pixelHeight', 'pixelsPerPoint']);
45+
assert.ok(table.captures.length > 0, 'the table must record at least one measured capture');
46+
for (const capture of table.captures) {
47+
assert.deepEqual(
48+
Object.keys(capture.metadata).sort(),
49+
[...table.fields].sort(),
50+
`${capture.name}: carries exactly the declared fields`,
51+
);
52+
}
53+
});
54+
55+
test('reads every measured capture the golden table records', () => {
56+
const table = readTable();
57+
for (const capture of table.captures) {
58+
const read = readRunnerScreenCaptureMetadata(runnerPayload(capture.metadata, table.key));
59+
assert.deepEqual(read, capture.metadata, capture.name);
60+
// The reader returns exactly the facts the table declares, so a consumer cannot quietly receive
61+
// a fifth number nobody pinned against the encoder.
62+
assert.deepEqual(Object.keys(read ?? {}).sort(), [...table.fields].sort(), capture.name);
63+
}
64+
});
65+
66+
test('refuses a payload missing any fact the golden table declares', () => {
67+
const table = readTable();
68+
const [measured] = table.captures;
69+
assert(measured, 'the golden table must record at least one measured capture');
70+
for (const field of table.fields) {
71+
const partial: Record<string, number> = { ...measured.metadata };
72+
delete partial[field];
73+
assert.equal(
74+
readRunnerScreenCaptureMetadata(runnerPayload(partial, table.key)),
75+
undefined,
76+
`${measured.name}: missing ${field}`,
77+
);
78+
}
79+
});
80+
81+
test('reports no source fact when the runner carried no metadata', () => {
82+
assert.equal(readRunnerScreenCaptureMetadata({ message: 'tmp/screenshot-1.png' }), undefined);
83+
});
84+
85+
const OPEN_DUO_CAPTURE = {
86+
displayID: 3,
87+
pixelWidth: 2852,
88+
pixelHeight: 2006,
89+
pixelsPerPoint: 3,
90+
};
91+
92+
test.each([
93+
['a non-object payload', 'not-an-object'],
94+
['an array payload', [OPEN_DUO_CAPTURE]],
95+
['the pre-panel scale probe value leaking in as zero', { ...OPEN_DUO_CAPTURE, displayID: 0 }],
96+
['a zero-scale image', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: 0 }],
97+
['a non-integer pixel box', { ...OPEN_DUO_CAPTURE, pixelWidth: 2852.5 }],
98+
['a missing side', { displayID: 3, pixelWidth: 2852, pixelsPerPoint: 3 }],
99+
['a negative scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: -3 }],
100+
['a non-numeric scale', { ...OPEN_DUO_CAPTURE, pixelsPerPoint: '3' }],
101+
])('refuses %s rather than guessing a capture scale', (_case, metadata) => {
102+
assert.equal(readRunnerScreenCaptureMetadata(runnerPayload(metadata)), undefined);
103+
});
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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 TypeScript owns the reader here, so
8+
* the wire key, the field names and a real measured capture are declared once by the golden table
9+
* `contracts/fixtures/screen-capture-metadata.json`. That table is asserted by
10+
* `packages/contracts/src/screen-capture-contract.test.ts` and by the runner unit-test lane in
11+
* `UnitTests/RunnerTests+AppScreenCaptureTests.swift`; a consumer may not restate this shape as a
12+
* local literal or read it through an unchecked cast.
13+
*/
14+
15+
/** The `data` key a runner screenshot result carries its display facts under. */
16+
const RUNNER_SCREEN_CAPTURE_METADATA_KEY = 'screenshotMetadata';
17+
18+
/**
19+
* What one runner capture measured about itself. `pixelsPerPoint` is the scale of the image the
20+
* runner encoded, `pixelWidth`/`pixelHeight` are that encoded image's own box after the runner drew
21+
* it upright, and `displayID` is the screen the window reported — never a screen chosen by number
22+
* or by position in a screen list.
23+
*/
24+
export type RunnerScreenCaptureMetadata = Readonly<{
25+
displayID: number;
26+
pixelWidth: number;
27+
pixelHeight: number;
28+
pixelsPerPoint: number;
29+
}>;
30+
31+
/**
32+
* Reads the display facts out of a runner `data` payload. Returns undefined when the payload carries
33+
* none or carries a value that cannot describe a real capture, which leaves the consumer with no
34+
* source fact — the honest pre-panel state — rather than a number invented from a panel nobody
35+
* measured. The Swift encoder refuses to report a scale that is not finite and positive, so these
36+
* refusals are the host's defence against a payload that did not come from that encoder.
37+
*/
38+
export function readRunnerScreenCaptureMetadata(
39+
data: Record<string, unknown>,
40+
): RunnerScreenCaptureMetadata | undefined {
41+
const raw = data[RUNNER_SCREEN_CAPTURE_METADATA_KEY];
42+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
43+
const payload = raw as Record<string, unknown>;
44+
const displayID = readPositiveInteger(payload.displayID);
45+
const pixelWidth = readPositiveInteger(payload.pixelWidth);
46+
const pixelHeight = readPositiveInteger(payload.pixelHeight);
47+
const pixelsPerPoint = readPositiveFinite(payload.pixelsPerPoint);
48+
if (
49+
displayID === undefined ||
50+
pixelWidth === undefined ||
51+
pixelHeight === undefined ||
52+
pixelsPerPoint === undefined
53+
) {
54+
return undefined;
55+
}
56+
return Object.freeze({ displayID, pixelWidth, pixelHeight, pixelsPerPoint });
57+
}
58+
59+
function readPositiveInteger(value: unknown): number | undefined {
60+
return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
61+
}
62+
63+
function readPositiveFinite(value: unknown): number | undefined {
64+
return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
65+
}

0 commit comments

Comments
 (0)