Stabilize simulator integration runtime selection

DjDeveloperr · DjDeveloperr · commit a28d3b69f1e7 · 2026-05-11T22:55:11.000-04:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,7 +16,9 @@ env:
 jobs:
   rust:
     name: Rust lint and unit tests
-    runs-on: macos-latest
+    runs-on: macos-15
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_16.4.app/Contents/Developer
 
     steps:
       - uses: actions/checkout@v4
@@ -114,7 +116,9 @@ jobs:
 
   build-artifacts:
     name: Build integration artifacts
-    runs-on: macos-latest
+    runs-on: macos-15
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_16.4.app/Contents/Developer
 
     steps:
       - uses: actions/checkout@v4
@@ -169,7 +173,9 @@ jobs:
 
   integration-cli:
     name: CLI simulator integration
-    runs-on: macos-latest
+    runs-on: macos-15
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_16.4.app/Contents/Developer
     needs:
       - rust
       - client
@@ -199,7 +205,9 @@ jobs:
 
   integration-js-api:
     name: JS API simulator integration
-    runs-on: macos-latest
+    runs-on: macos-15
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_16.4.app/Contents/Developer
     needs:
       - rust
       - client
diff --git a/docs/guide/testing.md b/docs/guide/testing.md
@@ -72,12 +72,19 @@ Useful environment variables:
 | `SIMDECK_INTEGRATION_SHOW_SIMULATOR=1`  | Open Simulator.app during the run.                    |
 | `SIMDECK_INTEGRATION_KEEP_SIMULATOR=1`  | Leave the temporary simulator after exit.             |
 | `SIMDECK_INTEGRATION_SIMCTL_TIMEOUT_MS` | Override the cold CoreSimulator command timeout.      |
+| `SIMDECK_INTEGRATION_IOS_RUNTIME`       | Force a runtime by version, name, or identifier.      |
+| `SIMDECK_INTEGRATION_DEVICE_TYPE`       | Force an iPhone device type by name or identifier.    |
 
 The integration suite is separate from `npm run test` because it boots and drives a real iOS simulator.
 The UIKit fixture app is cached under `.cache/simdeck/fixture` using a hash
 of its generated source, plist, simulator SDK, Clang version, and host
 architecture.
 
+By default, the integration runner selects the newest available iOS runtime that
+does not exceed the active `iphonesimulator` SDK version, falling back to the
+same major version when needed. This keeps CI off newer installed runtimes that
+do not match the selected Xcode toolchain.
+
 ## Stress and Leak Checks
 
 Use the stress runner against an already-running daemon when you want to shake out
diff --git a/scripts/integration/cli.mjs b/scripts/integration/cli.mjs
@@ -5,6 +5,7 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { buildCachedFixtureApp } from "./fixture.mjs";
+import { selectIntegrationSimulator } from "./simulator-selection.mjs";
 
 const root = path.resolve(new URL("../..", import.meta.url).pathname);
 const simdeck = path.join(root, "build", "simdeck");
@@ -73,8 +74,11 @@ async function main() {
     throw new Error(`Missing ${simdeck}. Run npm run build:cli first.`);
   }
 
-  const runtime = latestAvailableIosRuntime();
-  const deviceType = preferredIphoneDeviceType(runtime);
+  const { runtime, deviceType, sdkVersion } = selectIntegrationSimulator({
+    runJson,
+    runText,
+    timeoutMs: coreSimulatorCommandTimeoutMs,
+  });
   const simulatorName = `SimDeck CLI Integration ${Date.now()}`;
   simulatorUDID = await measuredStep(
     "simctl create simulator",
@@ -90,7 +94,7 @@ async function main() {
   );
 
   console.log(
-    `created ${simulatorUDID} (${deviceType.name}, ${runtime.version})`,
+    `created ${simulatorUDID} (${deviceType.name}, ${runtime.version}; iphonesimulator SDK ${sdkVersion})`,
   );
   startServer();
   await measuredStep("server health", () => waitForHealth(), {
@@ -608,86 +612,6 @@ async function runRestControls() {
   );
 }
 
-function latestAvailableIosRuntime() {
-  const payload = runJson("xcrun", ["simctl", "list", "runtimes", "-j"], {
-    timeoutMs: coreSimulatorCommandTimeoutMs,
-  });
-  const runtimes = payload.runtimes
-    .filter(
-      (runtime) => runtime.isAvailable && runtime.identifier?.includes("iOS"),
-    )
-    .sort(compareRuntimeVersions);
-  const runtime = runtimes.at(-1);
-  if (!runtime) {
-    throw new Error("No available iOS simulator runtime found.");
-  }
-  return runtime;
-}
-
-function preferredIphoneDeviceType(runtime) {
-  const runtimeSupported = Array.isArray(runtime.supportedDeviceTypes)
-    ? runtime.supportedDeviceTypes
-    : [];
-  const allDeviceTypes = runJson(
-    "xcrun",
-    ["simctl", "list", "devicetypes", "-j"],
-    { timeoutMs: coreSimulatorCommandTimeoutMs },
-  ).devicetypes;
-  const supported =
-    runtimeSupported.length > 0
-      ? runtimeSupported
-      : allDeviceTypes.filter(
-          (device) =>
-            device.productFamily === "iPhone" ||
-            device.identifier?.includes("iPhone"),
-        );
-  const iphones = supported.filter(
-    (device) =>
-      device.productFamily === "iPhone" ||
-      device.identifier?.includes("iPhone"),
-  );
-  const preferred = [
-    "iPhone 17",
-    "iPhone 16",
-    "iPhone 15",
-    "iPhone 14",
-    "iPhone 13",
-  ];
-  for (const name of preferred) {
-    const match = iphones.find((device) => device.name === name);
-    if (match) {
-      return match;
-    }
-  }
-  const fallback = iphones[0];
-  if (!fallback) {
-    throw new Error(
-      `Runtime ${runtime.identifier} does not support an iPhone device.`,
-    );
-  }
-  return fallback;
-}
-
-function compareRuntimeVersions(left, right) {
-  const leftParts = String(left.version ?? "0")
-    .split(".")
-    .map(Number);
-  const rightParts = String(right.version ?? "0")
-    .split(".")
-    .map(Number);
-  for (
-    let index = 0;
-    index < Math.max(leftParts.length, rightParts.length);
-    index += 1
-  ) {
-    const delta = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
-    if (delta !== 0) {
-      return delta;
-    }
-  }
-  return String(left.identifier).localeCompare(String(right.identifier));
-}
-
 function buildFixtureApp() {
   return buildCachedFixtureApp({
     root,
diff --git a/scripts/integration/js-api.mjs b/scripts/integration/js-api.mjs
@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { connect } from "simdeck/test";
 import { buildCachedFixtureApp } from "./fixture.mjs";
+import { selectIntegrationSimulator } from "./simulator-selection.mjs";
 
 const root = path.resolve(new URL("../..", import.meta.url).pathname);
 const simdeck = path.join(root, "build", "simdeck");
@@ -68,8 +69,11 @@ async function main() {
     );
   }
 
-  const runtime = latestAvailableIosRuntime();
-  const deviceType = preferredIphoneDeviceType(runtime);
+  const { runtime, deviceType, sdkVersion } = selectIntegrationSimulator({
+    runJson,
+    runText,
+    timeoutMs: coreSimulatorCommandTimeoutMs,
+  });
   const simulatorName = `SimDeck JS API Integration ${Date.now()}`;
   simulatorUDID = await measuredStep(
     "simctl create simulator",
@@ -84,7 +88,7 @@ async function main() {
     { phase: phaseSetup },
   );
   console.log(
-    `created ${simulatorUDID} (${deviceType.name}, ${runtime.version})`,
+    `created ${simulatorUDID} (${deviceType.name}, ${runtime.version}; iphonesimulator SDK ${sdkVersion})`,
   );
 
   await measuredStep(
@@ -326,83 +330,6 @@ async function expectElementContains(selector, text, options = {}) {
   );
 }
 
-function latestAvailableIosRuntime() {
-  const payload = runJson("xcrun", ["simctl", "list", "runtimes", "-j"], {
-    timeoutMs: coreSimulatorCommandTimeoutMs,
-  });
-  const runtimes = payload.runtimes
-    .filter(
-      (runtime) => runtime.isAvailable && runtime.identifier?.includes("iOS"),
-    )
-    .sort(compareRuntimeVersions);
-  const runtime = runtimes.at(-1);
-  if (!runtime) {
-    throw new Error("No available iOS simulator runtime found.");
-  }
-  return runtime;
-}
-
-function preferredIphoneDeviceType(runtime) {
-  const runtimeSupported = Array.isArray(runtime.supportedDeviceTypes)
-    ? runtime.supportedDeviceTypes
-    : [];
-  const allDeviceTypes = runJson(
-    "xcrun",
-    ["simctl", "list", "devicetypes", "-j"],
-    { timeoutMs: coreSimulatorCommandTimeoutMs },
-  ).devicetypes;
-  const supported =
-    runtimeSupported.length > 0
-      ? runtimeSupported
-      : allDeviceTypes.filter(
-          (device) =>
-            device.productFamily === "iPhone" ||
-            device.identifier?.includes("iPhone"),
-        );
-  const iphones = supported.filter(
-    (device) =>
-      device.productFamily === "iPhone" ||
-      device.identifier?.includes("iPhone"),
-  );
-  for (const name of [
-    "iPhone 17",
-    "iPhone 16",
-    "iPhone 15",
-    "iPhone 14",
-    "iPhone 13",
-  ]) {
-    const match = iphones.find((device) => device.name === name);
-    if (match) {
-      return match;
-    }
-  }
-  const fallback = iphones[0];
-  if (!fallback) {
-    throw new Error(
-      `Runtime ${runtime.identifier} does not support an iPhone device.`,
-    );
-  }
-  return fallback;
-}
-
-function compareRuntimeVersions(left, right) {
-  const leftParts = String(left.version ?? "0")
-    .split(".")
-    .map(Number);
-  const rightParts = String(right.version ?? "0")
-    .split(".")
-    .map(Number);
-  for (
-    let index = 0;
-    index < Math.max(leftParts.length, rightParts.length);
-    index += 1
-  ) {
-    const delta = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
-    if (delta !== 0) return delta;
-  }
-  return String(left.identifier).localeCompare(String(right.identifier));
-}
-
 function buildFixtureApp() {
   return buildCachedFixtureApp({
     root,
diff --git a/scripts/integration/simulator-selection.mjs b/scripts/integration/simulator-selection.mjs
