Compare commits

...
Author SHA1 Message Date
Brent Vatne 5888d46d6b Capture asks again for a session's simulator:control actions when the list fails, and a session that cannot switch to its appearance stops before folding
In brentvatne/euxy's main baseline run 39487618529, one failed `eas simulator:control --list` made the dark-appearance session look as if it offered no actions: it dropped dark, approved no link scheme, skipped the SpringBoard restart its fold needed, and failed the target the light session had captured.

A failed list is now asked for again after 3 s and 6 s, and one that still fails throws a retryable SIMULATOR_CONTROL_UNAVAILABLE. A session whose serve-sim or EAS CLI predates the list still has no actions, without retries. A session given only appearances it cannot switch to stops before installing the app or folding, and records those appearances' routes as not captured.
2026-10-20 13:42:16 -07:00
Brent Vatne fecf040ce5 Release 0.20.3 (#53) 2026-10-20 12:22:14 -07:00
7 changed files with 198 additions and 27 deletions

No files matched your search

+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.20.2",
"version": "0.20.3",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.20.2",
"version": "0.20.3",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.20.2",
"version": "0.20.3",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
+24 -3
View File
@@ -360,9 +360,10 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
let captureFailure: unknown;
const finish = async (): Promise<CiMapResult> => {
if (!(await store.exists())) await store.initialize(map, false);
// A session making only secondary passes owns the `<id>@<scheme>` frames of those passes, not the primary ones.
// A session making only secondary passes owns the `<id>@<scheme>` frames of those passes, not the primary ones, even
// when it could not switch to them and so captured none.
const ownFrameIds = options.appearancePass && !options.appearancePass.capture.includes(colorSchemes[0]!)
? selectedIds.flatMap(id => colorSchemes.filter(scheme => options.appearancePass!.capture.includes(scheme)).map(scheme => schemeScreenId(id, scheme)))
? selectedIds.flatMap(id => options.appearancePass!.capture.filter(scheme => scheme !== colorSchemes[0]).map(scheme => schemeScreenId(id, scheme)))
: selectedIds;
const incomplete = captureFailure !== undefined || ownFrameIds.some(id => outcomes[id]?.status !== "captured" || outcomes[id]?.landing !== "verified")
|| map.gaps.some(gap => gap.status === "open");
@@ -751,8 +752,28 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
connection = handoff.connection;
await rm(dotenvPath, { force: true });
if (options.platform === "ios") controlActions = simulatorControlActions(sessionEas, sessionId);
if (options.platform === "ios") controlActions = simulatorControlActions(sessionEas, sessionId, controlOptions);
if (!controlActions.has("appearance.set")) narrowToArgentScheme();
// A side split over sessions gives this one only some of its appearances (captureSideInSessions). One that cannot
// switch to any of them has nothing to capture, so it stops here, before the app is installed or the device folded:
// in brentvatne/euxy's main baseline run 39487618529, the dark session folded the device for frames it would never
// take, and its failed fold failed the target that the light session had captured.
const pass = options.appearancePass;
if (pass && !colorSchemes.some(scheme => pass.capture.includes(scheme))) {
const skipped = pass.capture.join(", ");
// The export merge needs the primary appearance's frames; a session that cannot take them fails the side.
if (pass.capture.includes(pass.all[0]!)) throw new CiError({ code: "SESSION_APPEARANCE_UNAVAILABLE", stage: "session", retryable: true,
message: `Simulator session ${sessionId} cannot switch to ${skipped}, the primary appearance it was given to capture.`,
nextAction: "Rerun the capture on a new session, or set capture.appearance to the appearance this controller renders." });
say(`session ${sessionId} cannot switch to ${skipped}, the appearance it was given; it stops without capturing, and the report has no ${skipped} frames`);
const error = { code: "SESSION_APPEARANCE_UNAVAILABLE", stage: "session", retryable: true,
message: `Simulator session ${sessionId} could not switch to ${skipped}.`, nextAction: "Rerun the capture on a new session." };
for (const id of selectedIds) for (const scheme of pass.capture) {
outcomes[schemeScreenId(id, scheme)] = { status: "failed", attempts: 0, landing: "unverified", reason: error.message, error };
}
// The finally block below stops the session after the export.
return await finish();
}
}
const controllerConfig = join(simulatorProject, "agent-device.json");
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
+56 -17
View File
@@ -1,24 +1,11 @@
import { CiError } from "../shared/ci-errors.js";
import { isRecord } from "./common.js";
/** Runs the pinned EAS CLI with these arguments; throws when it exits non-zero unless `allowFailure` is set. */
export type EasCommand = (args: string[], options?: { timeoutMs?: number; allowFailure?: boolean }) => { stdout: string; stderr?: string };
/**
* The host actions an EAS Simulator iOS session offers through `eas simulator:control` (serve-sim's actions, 0.10.0 and
* later for the ones Explore uses): an empty set when the session or the EAS CLI offers none, so a caller falls back to
* what it did before them. The session is always named by id, never taken from a `.env.eas-simulator` beside it.
*
* These are a fallback: what the session's controller can do itself (agent-device or Argent: fold, appearance, a
* reader reset) goes through the controller. Explore uses an action here only for what neither controller offers —
* approving a link scheme, restarting SpringBoard, and Argent's appearance (software-mansion/argent#1509).
* Runs the pinned EAS CLI with these arguments; throws when it exits non-zero unless `allowFailure` is set. A runner that
* knows the exit status reports it as `status`.
*/
export function simulatorControlActions(eas: EasCommand, sessionId: string): Set<string> {
try {
const listed = eas(["simulator:control", "--list", "--id", sessionId, "--json", "--non-interactive"], { timeoutMs: 2 * 60_000, allowFailure: true });
const actions = JSON.parse(listed.stdout) as unknown;
return new Set(isRecord(actions) ? Object.keys(actions) : []);
} catch { return new Set(); }
}
export type EasCommand = (args: string[], options?: { timeoutMs?: number; allowFailure?: boolean }) => { stdout: string; stderr?: string; status?: number | null };
/**
* Pauses before each resend of a failed action. Every action Explore runs is idempotent, and the session's host can fail
@@ -27,6 +14,58 @@ export function simulatorControlActions(eas: EasCommand, sessionId: string): Set
*/
const SIMULATOR_CONTROL_RETRY_DELAYS_MS = [3_000, 6_000] as const;
/**
* What eas-cli 25.2.0 says when the session's serve-sim predates the action list (it refuses `actions.describe`, or
* answers it without a catalog), and what an EAS CLI without `simulator:control` says. Those sessions offer no actions,
* and asking again would not change that.
*/
const NO_ACTION_LIST = /serve-sim version that does not support this action|did not return its list of actions|command simulator:control not found/;
/**
* The host actions an EAS Simulator iOS session offers through `eas simulator:control` (serve-sim's actions, 0.10.0 and
* later for the ones Explore uses): an empty set when the session's serve-sim or the EAS CLI predates the list, so a
* caller falls back to what it did before them. The session is always named by id, never taken from a
* `.env.eas-simulator` beside it.
*
* These are a fallback: what the session's controller can do itself (agent-device or Argent: fold, appearance, a
* reader reset) goes through the controller. Explore uses an action here only for what neither controller offers —
* approving a link scheme, restarting SpringBoard, and Argent's appearance (software-mansion/argent#1509).
*
* eas-cli prints the list as JSON on stdout only when it succeeds; a failure prints its reason on stderr. A list that
* fails is asked for again after a pause, and one that still fails throws a retryable error rather than reading as "no
* actions": in brentvatne/euxy's main baseline run 39487618529, one failed list made the dark-appearance session look as
* if it offered none, so it dropped dark, approved no link scheme, and skipped the SpringBoard restart its fold needed,
* which failed the target. A session whose host cannot answer three times in a row would fail those actions too, and
* capturing on without them publishes a report that silently lacks an appearance; a new session is the way out.
*/
export function simulatorControlActions(eas: EasCommand, sessionId: string, options: SimulatorControlOptions = {}): Set<string> {
const sleep = options.sleep ?? (milliseconds => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds); });
const args = ["simulator:control", "--list", "--id", sessionId, "--json", "--non-interactive"];
for (let retry = 0; ; retry += 1) {
let failure: string;
try {
const listed = eas(args, { timeoutMs: 2 * 60_000, allowFailure: true });
const actions = (() => { try { return JSON.parse(listed.stdout) as unknown; } catch { return undefined; } })();
if ((listed.status ?? 0) === 0 && isRecord(actions)) return new Set(Object.keys(actions));
const output = `${listed.stderr ?? ""}\n${listed.stdout}`;
if (NO_ACTION_LIST.test(output)) return new Set();
// eas-cli ends a failure with "simulator:control command failed."; the line before it says why.
failure = output.split("\n").map(line => line.trim()).filter(line => line && !/command failed\.?$/.test(line)).at(-1)?.slice(0, 300) || "it printed no list";
} catch (error) {
if (NO_ACTION_LIST.test(error instanceof Error ? error.message : String(error))) return new Set();
failure = firstLine(error);
}
const delayMs = SIMULATOR_CONTROL_RETRY_DELAYS_MS[retry];
if (delayMs === undefined) throw new CiError({ code: "SIMULATOR_CONTROL_UNAVAILABLE", stage: "session", retryable: true,
message: `EAS could not list the simulator:control actions of session ${sessionId} after ${retry + 1} attempts: ${failure}`,
nextAction: "Rerun the capture on a new session. Without the list, Explore cannot tell whether the session can switch appearance, approve the app's links, or restart SpringBoard.",
details: { sessionId, attempts: retry + 1 } });
// A list that succeeds on a later attempt would otherwise leave no trace of the failure in the job log.
process.stderr.write(`simulator:control --list failed for session ${sessionId} (${failure}); asking again in ${delayMs / 1000} s\n`);
sleep(delayMs);
}
}
/** Lets a test replace the pause between resends of a failed action. */
export type SimulatorControlOptions = { sleep?: ((milliseconds: number) => void) | undefined };
+2
View File
@@ -169,6 +169,8 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
}
if (command === 'simulator:get') { const session = sessions.get(value(request, '--id')); return json({ id: session.id, name: session.name, type: 'agent-device', platform: platform.toUpperCase(), status: 'IN_PROGRESS', app: { id: PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } }, remoteConfig: { agentDeviceRemoteSessionUrl: `https://controller.example/${session.id}`, agentDeviceRemoteSessionToken: 'controller-private-token' } }); }
if (command === 'simulator:stop') return json({ id: value(request, '--id'), status: 'STOPPED' });
// The session's serve-sim offers no simulator:control actions, so the capture falls back to the controller's own.
if (command === 'simulator:control' && request.args.includes('--list')) return json({});
}
if (basename(request.command) === 'repack-app') {
repackedSha = git(request.cwd, 'rev-parse', 'HEAD');
+61 -1
View File
@@ -129,6 +129,8 @@ async function fixture(t, settings = {}) {
let enteredName = false; let scrolledToContinue = false; let finishHidden = false; let wedgeCleared = false; let deviceLost = false; let relaunchedAfterForeign = false; let serverStarts = 0; let unreadableLeft = settings.unreadableAfterFold ?? 0;
// startsErrored / startsUnnamed: how many session starts EAS fails, after naming the session (it ERRORS) or before.
let starts = 0; let currentSession = 'session-1'; const erroredSessions = new Set(); let foldUnverifiedLeft = settings.foldUnverified ?? 0;
// listFailures: the first so many `simulator:control --list` calls fail, as a host that drops the connection does.
let listFailuresLeft = settings.listFailures ?? 0;
// focusedField: the screen at `path` focuses its text field, and the keyboard is up from the `keyboardFrom`th read of it.
let focusedReads = 0;
// blackAfterFold: the first so many folds of an EAS agent-device session light the panel but draw nothing.
@@ -207,7 +209,10 @@ async function fixture(t, settings = {}) {
// controlActions: what the session's serve-sim offers through simulator:control (none unless a test names them).
if (command === 'simulator:control') {
assert.equal(value(request, '--id'), currentSession, 'simulator:control names the session');
if (request.args.includes('--list')) return json(Object.fromEntries((settings.controlActions ?? []).map(action => [action, { type: 'object' }])));
if (request.args.includes('--list')) {
if (listFailuresLeft > 0) { listFailuresLeft -= 1; return { stdout: '', stderr: 'The simulator preview server closed the connection before it answered.\nError: simulator:control command failed.\n' }; }
return json(Object.fromEntries((settings.controlActions ?? []).map(action => [action, { type: 'object' }])));
}
assert.ok((settings.controlActions ?? []).includes(request.args[1]), `${request.args[1]} is offered by the session`);
if (request.args[1] === 'appearance.set') appearance = request.args.at(-1);
return json({ id: currentSession, action: request.args[1], output: '' });
@@ -592,6 +597,61 @@ test('when a fold on EAS leaves Argent reading the dark panel, the capture resta
}
});
// In brentvatne/euxy's main baseline run 39487618529, one failed --list made the dark session look as if it offered no
// actions: it dropped dark, approved no link scheme, skipped the SpringBoard restart its fold needed, and failed the target.
test('a --list that fails once still gives an Argent dark session its appearance, its link approval and its fold recovery', async t => {
const f = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', devicePose: 'open', foldUnverified: 1, listFailures: 1,
controlActions: ['appearance.set', 'app.approveUrlScheme', 'springboard.restart'] });
const lines = [];
const result = await runCiMap({ ...f.options, progress: line => lines.push(line), appearancePass: { all: ['light', 'dark'], capture: ['dark'] } });
assert.equal(result.runStatus, 'complete');
const control = f.requests.filter(request => request.args[0] === 'simulator:control');
assert.equal(control.filter(request => request.args.includes('--list')).length, 2);
assert.equal(lines.some(line => /Argent cannot switch appearance/.test(line)), false, lines.join('\n'));
assert.deepEqual(control.filter(request => request.args[1] === 'appearance.set').map(request => request.args.at(-1)), ['dark']);
assert.equal(control.filter(request => request.args[1] === 'app.approveUrlScheme').length, 1);
assert.equal(control.filter(request => request.args[1] === 'springboard.restart').length, 1);
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.deepEqual(Object.keys(bundle.images).sort(), [`${f.ids.home}@dark`, `${f.ids.settings}@dark`]);
});
test('a --list that keeps failing fails the session with a retryable error before the app is installed, and stops the session', async t => {
const f = await fixture(t, { argent: true, devicePose: 'open', listFailures: Infinity, controlActions: ['springboard.restart'] });
await assert.rejects(runCiMap(f.options), error => error.code === 'SIMULATOR_CONTROL_UNAVAILABLE' && error.retryable === true);
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args.includes('--list')).length, 3);
assert.equal(f.requests.some(request => request.command.endsWith('/argent-controller') && ['install', 'fold'].includes(request.args[0])), false);
assert.equal(f.operations().filter(operation => operation === 'simulator:stop').length, 1);
});
test('a session given only dark that cannot switch to it stops before installing or folding, and the merge keeps the light session\'s capture', async t => {
const dark = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', devicePose: 'open' });
const lines = [];
await runCiMap({ ...dark.options, progress: line => lines.push(line), appearancePass: { all: ['light', 'dark'], capture: ['dark'] } });
assert.equal(dark.requests.some(request => request.command.endsWith('/argent-controller') && ['install', 'fold'].includes(request.args[0])), false);
assert.equal(dark.operations().filter(operation => operation === 'simulator:stop').length, 1);
assert.ok(lines.some(line => /session session-1 cannot switch to dark, the appearance it was given; it stops without capturing/.test(line)), lines.join('\n'));
const idle = JSON.parse(await readFile(join(dark.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.deepEqual(Object.keys(idle.images), []);
assert.equal(idle.outcomes[`${dark.ids.home}@dark`].error.code, 'SESSION_APPEARANCE_UNAVAILABLE');
// A light session that switched appearance expects dark: each route's dark frame is reported as not captured.
// One that could not switch either captured light alone, as one session would have: the dark session adds nothing.
for (const [actions, expected] of [[['appearance.set'], 'failed'], [[], undefined]]) {
const light = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', devicePose: 'open', controlActions: actions });
await runCiMap({ ...light.options, appearancePass: { all: ['light', 'dark'], capture: ['light'] } });
await mergeCaptureExports(light.options.outputDirectory, [{ directory: dark.options.outputDirectory, scheme: 'dark' }]);
const merged = JSON.parse(await readFile(join(light.options.outputDirectory, 'bundle.json'), 'utf8'));
for (const id of Object.values(light.ids)) {
assert.equal(merged.outcomes[id].status, 'captured', id);
assert.equal(merged.outcomes[`${id}@dark`]?.status, expected, `${id}@dark with ${actions.join(', ') || 'no actions'}`);
}
}
// A session that cannot take the side's primary appearance fails it: the merge has nothing to add the others to.
const primary = await fixture(t, { argent: true, devicePose: 'open' });
await assert.rejects(runCiMap({ ...primary.options, appearance: ['dark', 'light'], appearancePass: { all: ['dark', 'light'], capture: ['dark'] } }),
error => error.code === 'SESSION_APPEARANCE_UNAVAILABLE');
assert.equal(primary.requests.some(request => request.command.endsWith('/argent-controller') && request.args[0] === 'fold'), false);
});
test('a session EAS ends while starting is replaced by a new one, under a name of its own, up to five times with a growing wait', async t => {
const f = await fixture(t, { startsErrored: 1 });
const lines = []; const waits = [];
+52 -3
View File
@@ -14,13 +14,62 @@ function easFake(listed) {
return { calls, eas };
}
test("a session's control actions come from --list, by session id; an older session or CLI has none", () => {
test("a session's control actions come from --list, by session id", () => {
const { calls, eas } = easFake(JSON.stringify({ "appearance.set": {}, "springboard.restart": {} }));
assert.deepEqual([...simulatorControlActions(eas, "session-1")], ["appearance.set", "springboard.restart"]);
assert.deepEqual(calls[0].args, ["simulator:control", "--list", "--id", "session-1", "--json", "--non-interactive"]);
assert.equal(calls[0].options.allowFailure, true);
assert.equal(simulatorControlActions(easFake("Unknown command simulator:control").eas, "session-1").size, 0);
assert.equal(simulatorControlActions(easFake(new Error("eas exited 1")).eas, "session-1").size, 0);
});
test("a session that lists no actions, or whose serve-sim or EAS CLI predates the list, has none, and is asked once", () => {
const pauses = [];
const options = { sleep: milliseconds => pauses.push(milliseconds) };
const empty = easFake("{}");
assert.equal(simulatorControlActions(empty.eas, "session-1", options).size, 0);
assert.equal(empty.calls.length, 1);
// eas-cli 25.2.0 on a session whose serve-sim refuses `actions.describe`, and an EAS CLI without simulator:control.
for (const reason of ["This simulator session runs a serve-sim version that does not support this action. Start a new session with `eas simulator:start` to get a newer version.",
"The simulator did not return its list of actions. Start a new session with `eas simulator:start` to get a newer serve-sim version."]) {
const calls = [];
const eas = args => { calls.push(args); return { stdout: "", stderr: `${reason}\nError: simulator:control command failed.\n`, status: 1 }; };
assert.equal(simulatorControlActions(eas, "session-1", options).size, 0);
assert.equal(calls.length, 1);
}
assert.equal(simulatorControlActions(easFake(new Error("eas exited with status 2: command simulator:control not found")).eas, "session-1", options).size, 0);
assert.deepEqual(pauses, []);
});
// One failed list made the dark session of euxy's main baseline run 39487618529 look as if it offered no actions.
function flakyList(failures, failure = () => ({ stdout: "", stderr: "The simulator preview server closed the connection before it answered.\nError: simulator:control command failed.\n", status: 1 })) {
const calls = [];
const eas = args => {
calls.push(args);
if (calls.length <= failures) return failure(calls.length);
return { stdout: JSON.stringify({ "appearance.set": {}, "app.approveUrlScheme": {}, "springboard.restart": {} }), stderr: "", status: 0 };
};
return { calls, eas };
}
test("a list that fails once is asked for again after a pause, and its actions are kept", () => {
for (const failure of [undefined, () => { throw new Error("eas simulator:control exited with status 1"); }, () => ({ stdout: "Connecting", stderr: "" })]) {
const { calls, eas } = flakyList(1, failure);
const pauses = [];
assert.deepEqual([...simulatorControlActions(eas, "session-1", { sleep: milliseconds => pauses.push(milliseconds) })], ["appearance.set", "app.approveUrlScheme", "springboard.restart"]);
assert.equal(calls.length, 2);
assert.deepEqual(calls[1], calls[0]);
assert.equal(pauses.length, 1);
}
});
test("a list that keeps failing throws a retryable error naming the session and EAS's reason, never an empty set", () => {
const { calls, eas } = flakyList(Infinity);
const pauses = [];
assert.throws(() => simulatorControlActions(eas, "session-1", { sleep: milliseconds => pauses.push(milliseconds) }), error =>
error.code === "SIMULATOR_CONTROL_UNAVAILABLE" && error.retryable === true && error.stage === "session"
&& /session-1/.test(error.message) && /closed the connection before it answered/.test(error.message) && !/command failed/.test(error.message));
assert.equal(calls.length, 3);
assert.equal(pauses.length, calls.length - 1);
assert.ok(pauses.every(milliseconds => milliseconds > 0 && milliseconds <= 10_000));
});
test("an action's values follow --, so one that starts with a dash is never read as a flag", () => {