@swmansion/argent 0.32.1-next.2 → 0.32.1-next.4

package/dist/cli-cmds.mjs

@@ -10708,6 +10708,8 @@ var FAILURE_CODES = {
   FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
   FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
   FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+  // The target does not satisfy the test's `requires:` block; a directory run skips it.
+  FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
   PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
   PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
   PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",
@@ -35809,7 +35811,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.2";
+    return "0.32.1-next.3";
   }
   return "0.0.0";
 }
@@ -37150,8 +37152,9 @@ contain only letters, numbers, "_", or "-" \u2014 the same charset a name must
 match. A test is standalone when its first non-\`echo\`/\`script\` step is \`launch\`.
 Other tests are fragments and use the device's current state. Exception: a fragment whose first step \`run:\`s a chromium standalone
 test boots that test's app before step 1 \u2014 when that launch is unambiguously
-chromium (a lone \`{ chromium: ... }\` target, or --platform chromium); a
-multi-platform launch auto-detects a device instead. Pass --device to attach to
+chromium (a lone \`{ chromium: ... }\` target, --platform chromium, or a
+\`requires:\` block that allows only chromium); a multi-platform launch
+auto-detects a device instead. Pass --device to attach to
 a running instance.
 
 A directory run prints only the steps that need attention (each failure, each
@@ -37164,6 +37167,12 @@ file, or a device it cannot resolve. A transport failure, a rejection the server
 does not mark as validation, or a reply that is not a report stops the batch and
 counts the remaining tests skipped.
 
+A test can declare a \`requires:\` block (platform, runtimeKind) that names the
+targets it supports. A directory run skips each test whose requirements the
+target does not meet, so the same directory runs on each platform without a
+separate list of tests. A single-test run fails instead. A directory run where
+no test ran exits 2.
+
 The CLI sends a run to its tool-server: the local one that starts
 automatically, or the one that \`argent link\` or ARGENT_TOOLS_URL names. Over
 a link, the CLI uploads these files and writes the new baselines that the run
@@ -37346,7 +37355,8 @@ function renderFailedSteps(report) {
   return lines;
 }
 function renderBatchSummary(counts, durationMs) {
-  return `${counts.failed === 0 ? "PASS" : "FAIL"} \u2014 ${counts.total} e2e test${counts.total === 1 ? "" : "s"}: ${counts.passed} passed, ${counts.failed} failed, ${counts.skipped} skipped${durationSuffix(durationMs)}`;
+  const verdict = counts.failed > 0 ? "FAIL" : counts.passed === 0 ? "NONE RAN" : "PASS";
+  return `${verdict} \u2014 ${counts.total} e2e test${counts.total === 1 ? "" : "s"}: ${counts.passed} passed, ${counts.failed} failed, ${counts.skipped} skipped${durationSuffix(durationMs)}`;
 }
 function summarizeFailure(report) {
   let n3 = 0;
@@ -37734,6 +37744,8 @@ function rejectionVerdict(code) {
       return "not run (invalid e2e test)";
     case FAILURE_CODES.FLOW_DEVICE_RESOLUTION:
       return "not run (no device resolved)";
+    case FAILURE_CODES.FLOW_REQUIREMENTS_UNMET:
+      return "not run (requires not met)";
     case FAILURE_CODES.FILE_INPUT_UPLOAD_FAILED:
       return "not run (upload failed)";
     default:
@@ -37810,6 +37822,14 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
       const err = unreachableErr ?? thrown;
       const message = err instanceof Error ? err.message : String(err);
       const toolErr = err instanceof ToolInvocationError ? err : void 0;
+      if (toolErr?.errorCode === FAILURE_CODES.FLOW_REQUIREMENTS_UNMET) {
+        const reason = message.replace(/^\[Tool:[^\]]+\] /, "");
+        results.push({ path: rel, status: "skip", reason });
+        if (!args.json)
+          console.log(`  ${STATUS_GLYPH.skip} skipped (requires not met)
+    ${reason}`);
+        continue;
+      }
       const rejectedThisFlowOnly = toolErr?.errorKind === "validation";
       const verdict = unreachableErr ? UNREACHABLE_VERDICT : rejectedThisFlowOnly ? rejectionVerdict(toolErr?.errorCode) : "did not finish (run error)";
       if (!args.json) console.log(`  ${STATUS_GLYPH.error} ${verdict}`);
@@ -37860,11 +37880,18 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     skipped: results.filter((r2) => r2.status === "skip").length
   };
   const durationMs = Date.now() - batchStartedAt;
+  const noneRan = counts.passed === 0 && counts.failed === 0;
   if (args.json) {
     console.log(
       JSON.stringify(
         // `flows` is the deprecated spelling of `e2eTests`.
-        { ok: counts.failed === 0, ...counts, durationMs, e2eTests: results, flows: results },
+        {
+          ok: counts.failed === 0 && !noneRan,
+          ...counts,
+          durationMs,
+          e2eTests: results,
+          flows: results
+        },
         null,
         2
       )
@@ -37873,8 +37900,9 @@ async function runFlowDirectory(dir, args, projectRoot, options) {
     for (const line of renderFailedFlows(failures)) console.log(line);
     console.log(`
 ${renderBatchSummary(counts, durationMs)}`);
+    if (noneRan) console.error(`No e2e test in ${dir} ran on the selected target.`);
   }
-  return exitAfterFlush(unreachable ? 2 : counts.failed === 0 ? 0 : 1);
+  return exitAfterFlush(unreachable || noneRan ? 2 : counts.failed === 0 ? 0 : 1);
 }
 async function e2e(argv, options) {
   const [sub, ...rest] = argv;

package/dist/client.js

@@ -9281,6 +9281,8 @@ var FAILURE_CODES = {
   FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
   FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
   FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+  // The target does not satisfy the test's `requires:` block; a directory run skips it.
+  FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
   PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
   PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
   PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",

package/dist/installer.mjs

@@ -16045,6 +16045,8 @@ var FAILURE_CODES = {
   FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
   FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
   FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+  // The target does not satisfy the test's `requires:` block; a directory run skips it.
+  FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
   PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
   PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
   PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",
@@ -16934,7 +16936,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.2";
+    return "0.32.1-next.3";
   }
   return "0.0.0";
 }

package/dist/mcp-server.mjs

@@ -25991,6 +25991,8 @@ var FAILURE_CODES = {
   FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
   FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
   FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+  // The target does not satisfy the test's `requires:` block; a directory run skips it.
+  FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
   PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
   PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
   PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",

package/dist/tool-args.generated.d.ts

@@ -231,9 +231,9 @@ export interface ArgentToolArgs {
         e2e_test_file?: string;
         /** Absolute path to an e2e test .yaml on the client. */
         e2e_test_path?: string;
-        /** Device id to run against (iOS UDID, Android/Vega serial, Chromium id), as list-devices reports it. Auto-detected when omitted, but only when exactly one booted device matches; with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up. */
+        /** Device id to run against (iOS UDID, Android/Vega serial, Chromium id), as list-devices reports it. Auto-detected when omitted, but only when exactly one booted device matches (optionally narrowed by `platform` and the e2e test's `requires:` block); with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up. */
         device?: string;
-        /** Restrict auto-detection to this platform when several devices are booted. `ios` selects local simulators only; `ios-remote` selects a remote one. `chromium` with no `device` also makes the runner boot an Electron instance for a standalone e2e test from its `launch` step's chromium value and tear it down after the run, with no fallback to auto-detection (a single-key `launch: { chromium: … }` map does this on its own; a fragment, or a launch map without a `chromium` key, is still auto-detected). That value must be an Electron app path on the tool-server host: the bare-string `launch:` the recorder writes holds a bundle id, which fails the run with `Electron boot: path does not exist`, so first edit it to `{ chromium: <app path> }`. */
+        /** Restrict auto-detection to this platform when several devices are booted. `ios` selects local simulators only; `ios-remote` selects a remote one. `chromium` with no `device` also makes the runner boot an Electron instance for a standalone e2e test from its `launch` step's chromium value and tear it down after the run, with no fallback to auto-detection (a single-key `launch: { chromium: … }` map, or a `requires:` block that allows only chromium, does this on its own; a fragment, or a launch map without a `chromium` key, is still auto-detected). That value must be an Electron app path on the tool-server host: the bare-string `launch:` the recorder writes holds a bundle id, which fails the run with `Electron boot: path does not exist`, so first edit it to `{ chromium: <app path> }`. */
         platform?: "ios" | "android" | "chromium" | "vega" | "ios-remote";
         /** Write/refresh screenshot baselines for `snapshot` steps instead of diffing against them, also in the e2e tests that tool: e2e-execute steps run, unless such a step sets updateBaselines itself. Over a link, the client writes the new baselines when the run ends. */
         updateBaselines?: boolean;
@@ -271,6 +271,11 @@ export interface ArgentToolArgs {
         project_root: string;
         /** Fragments only: the app/device state assumed on entry (e.g. "Settings app open on General page"). Omit it for a standalone e2e test. restart-app has no chromium support, so a chromium e2e test records as a fragment; add the `launch: { chromium: <app path> }` line to the YAML afterward, deleting the executionPrerequisite line if you passed one, since an e2e test that starts with a launch must not declare it. */
         executionPrerequisite?: string;
+        /** The e2e test's `requires:` block: the targets it supports, ANDed. `platform` is one platform or a list (`ios` also covers a remote simulator); `runtimeKind` is `tv` or `mobile`. Omit it for a test that runs on any target. */
+        requires?: {
+            platform?: "ios" | "android" | "chromium" | "vega" | Array<"ios" | "android" | "chromium" | "vega">;
+            runtimeKind?: "mobile" | "tv";
+        };
     };
     fill: {
         /** Target device id from `list-devices`. */

package/dist/tool-server.cjs

@@ -1751,6 +1751,8 @@ var init_failure_codes = __esm({
       FLOW_ENTRY_UNRECOGNIZED: "FLOW_ENTRY_UNRECOGNIZED",
       FLOW_E2E_HAS_PREREQUISITE: "FLOW_E2E_HAS_PREREQUISITE",
       FLOW_DEVICE_RESOLUTION: "FLOW_DEVICE_RESOLUTION",
+      // The target does not satisfy the test's `requires:` block; a directory run skips it.
+      FLOW_REQUIREMENTS_UNMET: "FLOW_REQUIREMENTS_UNMET",
       PROFILER_QUERY_MODE_INVALID: "PROFILER_QUERY_MODE_INVALID",
       PROFILER_QUERY_REQUIRED_PARAM_MISSING: "PROFILER_QUERY_REQUIRED_PARAM_MISSING",
       PROFILER_DATA_NOT_LOADED: "PROFILER_DATA_NOT_LOADED",
@@ -101157,7 +101159,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.2";
+    return "0.32.1-next.3";
   }
   return "0.0.0";
 }
@@ -103751,22 +103753,24 @@ async function simctlListDevices(options) {
   }
 }
 var remoteRuntimeKindCache = /* @__PURE__ */ new Map();
-async function isRemoteTvOsSimulator(udid, options) {
+async function getRemoteSimulatorRuntimeKind(udid, options) {
   const id = stripRemotePrefix(udid);
   const cached3 = remoteRuntimeKindCache.get(id);
-  if (cached3) return cached3 === "tv";
+  if (cached3) return cached3;
   try {
     const { devices } = await simctlListDevices(options);
     for (const [runtime, entries] of Object.entries(devices)) {
       if (!entries.some((d) => d.udid === id)) continue;
       const kind = simulatorRuntimeKind(runtime);
-      if (!kind) return false;
-      remoteRuntimeKindCache.set(id, kind);
-      return kind === "tv";
+      if (kind) remoteRuntimeKindCache.set(id, kind);
+      return kind;
     }
   } catch {
   }
-  return false;
+  return void 0;
+}
+async function isRemoteTvOsSimulator(udid, options) {
+  return await getRemoteSimulatorRuntimeKind(udid, options) === "tv";
 }
 async function simctlBoot(udid) {
   await run(["simctl", "boot", stripRemotePrefix(udid)]);
@@ -126584,7 +126588,8 @@ async function listRemoteIosSimulators() {
           udid: withRemotePrefix(d.udid),
           name: d.name,
           state: d.state,
-          runtime
+          runtime,
+          runtimeKind: simulatorRuntimeKind(runtime)
         });
       }
     }
@@ -146094,6 +146099,8 @@ async function runChromium(api, params) {
     }
     await api.dispatchKeyEvent({
       type: "keyDown",
+      // Chromium needs carriage-return text for Enter's default form submission.
+      ...named.key === "Enter" ? { text: "\r" } : {},
       key: named.key,
       code: named.code,
       windowsVirtualKeyCode: named.windowsVirtualKeyCode
@@ -168886,6 +168893,7 @@ var FOLD_POSTURES = ["closed", "half-open", "open"];
 function isFoldPosture(value) {
   return typeof value === "string" && FOLD_POSTURES.includes(value);
 }
+var RUNTIME_KINDS = ["mobile", "tv"];
 function blockSteps(step) {
   return isBlockStep(step) ? step.steps : void 0;
 }
@@ -169691,6 +169699,42 @@ function authoringPlatform(platform) {
   return platform === "ios-remote" ? "ios" : platform;
 }
 var LAUNCH_MAP_KEYS = ["native", ...LAUNCH_PLATFORMS];
+var REQUIRES_KEYS = ["platform", "runtimeKind"];
+function parseRequires(raw) {
+  const bad = (detail) => badEntry({ requires: raw }, detail);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    bad(`requires must be a map of ${REQUIRES_KEYS.join(" / ")}`);
+  }
+  const b = raw;
+  rejectUnknownKeys({ requires: raw }, b, REQUIRES_KEYS, "requires");
+  const out = {};
+  if (b.platform !== void 0) {
+    const list = Array.isArray(b.platform) ? b.platform : [b.platform];
+    const oneOf2 = `one of ${LAUNCH_PLATFORMS.join(", ")}`;
+    if (list.length === 0) bad(`requires.platform must name at least ${oneOf2}`);
+    const platforms = [];
+    for (const p of list) {
+      if (typeof p !== "string" || !LAUNCH_PLATFORMS.includes(p)) {
+        bad(`requires.platform must be ${oneOf2} (or a list of them)`);
+      }
+      platforms.push(p);
+    }
+    out.platform = platforms;
+  }
+  if (b.runtimeKind !== void 0) {
+    const kind = b.runtimeKind;
+    if (typeof kind !== "string" || !RUNTIME_KINDS.includes(kind)) {
+      bad(`requires.runtimeKind must be one of ${RUNTIME_KINDS.join(", ")}`);
+    }
+    out.runtimeKind = kind;
+  }
+  if (out.platform === void 0 && out.runtimeKind === void 0) {
+    bad(
+      `requires must declare at least one of ${REQUIRES_KEYS.join(", ")} (omit the block for a flow that runs on any target)`
+    );
+  }
+  return out;
+}
 function rejectUnquotedLaunchArg(raw, args, where) {
   const i = args.findIndex((a) => typeof a === "number" || typeof a === "boolean");
   if (i === -1) return;
@@ -170576,8 +170620,17 @@ function fromYamlStep(raw, blockDepth = 0) {
   }
   return badEntry(raw, "unrecognized step kind");
 }
+function requiresToYaml({ platform, runtimeKind }) {
+  return {
+    ...platform ? { platform: platform.length === 1 ? platform[0] : platform } : {},
+    ...runtimeKind ? { runtimeKind } : {}
+  };
+}
 function serializeFlow(flow) {
-  const doc = { steps: flow.steps.map(toYamlStep) };
+  const doc = {
+    ...flow.requires ? { requires: requiresToYaml(flow.requires) } : {},
+    steps: flow.steps.map(toYamlStep)
+  };
   if (flow.executionPrerequisite) doc.executionPrerequisite = flow.executionPrerequisite;
   return (0, import_yaml.stringify)(doc, { blockQuote: false });
 }
@@ -170623,7 +170676,7 @@ function parseFlow(content) {
       error_kind: "validation"
     });
   }
-  const topKeys = ["executionPrerequisite", "steps"];
+  const topKeys = ["executionPrerequisite", "requires", "steps"];
   const unknownTop = Object.keys(parsed).filter((k) => !topKeys.includes(k));
   if (unknownTop.length > 0) {
     throw new FailureError(
@@ -170642,6 +170695,7 @@ function parseFlow(content) {
   });
   const flow = {
     executionPrerequisite: parsed.executionPrerequisite ?? "",
+    ...parsed.requires === void 0 ? {} : { requires: parseRequires(parsed.requires) },
     steps
   };
   validateFlow(flow);
@@ -170904,6 +170958,12 @@ var zodSchema66 = external_exports.object({
   ),
   executionPrerequisite: external_exports.string().optional().describe(
     'Fragments only: the app/device state assumed on entry (e.g. "Settings app open on General page"). Omit it for a standalone e2e test. restart-app has no chromium support, so a chromium e2e test records as a fragment; add the `launch: { chromium: <app path> }` line to the YAML afterward, deleting the executionPrerequisite line if you passed one, since an e2e test that starts with a launch must not declare it.'
+  ),
+  requires: external_exports.object({
+    platform: external_exports.union([external_exports.enum(LAUNCH_PLATFORMS), external_exports.array(external_exports.enum(LAUNCH_PLATFORMS)).min(1)]).optional(),
+    runtimeKind: external_exports.enum(RUNTIME_KINDS).optional()
+  }).optional().describe(
+    "The e2e test's `requires:` block: the targets it supports, ANDed. `platform` is one platform or a list (`ios` also covers a remote simulator); `runtimeKind` is `tv` or `mobile`. Omit it for a test that runs on any target."
   )
 });
 var flowStartRecordingTool = {
@@ -170924,7 +170984,9 @@ not hold, or may fail once converted to \`await:\`/\`assert:\`. A wait nested in
 recorded run-sequence gets no such warning, so read its \`toolResult\`. For a
 standalone e2e test, record a restart-app of the app under test as the FIRST step
 (captured as the e2e test's \`launch\` step); for a reusable fragment, skip that and
-pass executionPrerequisite instead. Use e2e-add-echo to add labels, and
+pass executionPrerequisite instead. Starting over an existing e2e test replaces the
+whole file, including its \`requires:\` block; pass \`requires\` to keep it.
+Use e2e-add-echo to add labels, and
 e2e-add-script to run a local .mjs file and record it as a \`script:\` step.
 Call e2e-finish-recording when done.
 
@@ -170949,6 +171011,7 @@ and without a link, an edit that renumbers the steps drops their warnings.`,
   async execute(_services, params, ctx) {
     const flow = {
       executionPrerequisite: params.executionPrerequisite ?? "",
+      ...params.requires ? { requires: parseRequires(params.requires) } : {},
       steps: []
     };
     validateFlow(flow);
@@ -171011,7 +171074,9 @@ init_device_info();
 
 // ../tool-server/src/tools/flows/flow-device.ts
 init_src2();
+init_adb();
 init_device_info();
+init_external_devices();
 var DEVICE_BIND_KEYS = ["udid", "device_id", "device"];
 var DEVICE_BIND_LIST_KEYS = ["devices"];
 var DEVICE_ARG_KEYS = DEVICE_BIND_KEYS;
@@ -171057,16 +171122,128 @@ function deviceResolutionError(message, all) {
     error_kind: "validation"
   });
 }
+function describeRequires(requires) {
+  const parts2 = [];
+  if (requires.platform) parts2.push(`platform: [${requires.platform.join(", ")}]`);
+  if (requires.runtimeKind) parts2.push(`runtimeKind: ${requires.runtimeKind}`);
+  return `requires: { ${parts2.join(", ")} }`;
+}
+function requirementsError(message, code = FAILURE_CODES.FLOW_REQUIREMENTS_UNMET) {
+  return new FailureError(message, {
+    error_code: code,
+    failure_stage: "flow_requirements",
+    failure_area: "tool_server",
+    error_kind: "validation"
+  });
+}
+var CONSTANT_RUNTIME_KIND = {
+  chromium: "mobile",
+  harmony: "mobile",
+  vega: "tv"
+};
+function platformMeets(platform, requires) {
+  if (requires.platform && !requires.platform.includes(authoringPlatform(platform))) {
+    return false;
+  }
+  const constant = CONSTANT_RUNTIME_KIND[platform];
+  return !(requires.runtimeKind && constant && constant !== requires.runtimeKind);
+}
+function assertPlatformMeetsRequires(platform, requires, target, subject2 = "This e2e test") {
+  if (!requires || platformMeets(platform, requires)) return;
+  throw requirementsError(
+    `${subject2} declares ${describeRequires(requires)}, which excludes ${target}.`
+  );
+}
+async function probeRuntimeKind(device) {
+  const constant = CONSTANT_RUNTIME_KIND[device.platform];
+  if (constant) return constant;
+  if (isIosPhysicalDevice(device)) return "mobile";
+  switch (device.platform) {
+    case "ios":
+      return getSimulatorRuntimeKind(device.id);
+    case "ios-remote":
+      return getRemoteSimulatorRuntimeKind(device.id);
+    case "android":
+      return getAndroidRuntimeKind(externalNativeId(device.id));
+    default:
+      return void 0;
+  }
+}
+async function assertDeviceMeetsRequires(device, requires, subject2 = "This e2e test") {
+  if (!requires) return;
+  assertPlatformMeetsRequires(
+    device.platform,
+    requires,
+    `device ${device.id} (${device.platform})`,
+    subject2
+  );
+  if (!requires.runtimeKind) return;
+  const kind = await probeRuntimeKind(device);
+  if (kind === void 0) {
+    throw unknownRuntimeKindError(requires, [`${device.id} (${device.platform})`], subject2);
+  }
+  if (kind !== requires.runtimeKind) {
+    throw requirementsError(
+      `${subject2} declares ${describeRequires(requires)}, which excludes device ${device.id} (${device.platform}, ${kind}).`
+    );
+  }
+}
+function unknownRuntimeKindError(requires, devices, subject2 = "This e2e test", remedy = "") {
+  return requirementsError(
+    `${subject2} declares ${describeRequires(requires)}, but the runtime kind of ${devices.join(", ")} could not be determined.${remedy}`,
+    FAILURE_CODES.FLOW_DEVICE_RESOLUTION
+  );
+}
+function listedRuntimeKind(d) {
+  return CONSTANT_RUNTIME_KIND[d.platform] ?? d.runtimeKind;
+}
+async function candidateRuntimeKind(d) {
+  const id = deviceEntryId(d);
+  return listedRuntimeKind(d) ?? (id ? probeRuntimeKind(resolveDevice(id)) : void 0);
+}
 async function resolveFlowDevice(registry2, ctx, opts) {
   if (opts.device) return resolveDevice(opts.device);
   const { devices } = await invokeSubTool(registry2, ctx, "list-devices", {});
   const booted = devices.filter(isBooted);
   const scoped = opts.platform ? booted.filter((d) => d.platform === opts.platform) : booted;
-  if (scoped.length === 1) {
-    const id = deviceEntryId(scoped[0]);
+  const requires = opts.requires;
+  const candidates = requires ? scoped.filter((d) => platformMeets(d.platform, requires)) : scoped;
+  const kinds = /* @__PURE__ */ new Map();
+  if (requires?.runtimeKind) {
+    const wanted = requires.runtimeKind;
+    const anyMatch = () => candidates.some((d) => kinds.get(d) === wanted);
+    for (const d of candidates) kinds.set(d, listedRuntimeKind(d));
+    if (!anyMatch()) {
+      for (const d of candidates) {
+        if (kinds.get(d) === void 0) kinds.set(d, await candidateRuntimeKind(d));
+      }
+      const unknown2 = candidates.filter((d) => kinds.get(d) === void 0);
+      if (!anyMatch() && unknown2.length > 0) {
+        throw unknownRuntimeKindError(
+          requires,
+          unknown2.map(describeDevice),
+          void 0,
+          " Pass --device or --platform to choose a device."
+        );
+      }
+    }
+  }
+  const eligible = requires?.runtimeKind ? candidates.filter((d) => kinds.get(d) === requires.runtimeKind) : candidates;
+  if (eligible.length === 1) {
+    const id = deviceEntryId(eligible[0]);
     if (id) return resolveDevice(id);
   }
-  if (scoped.length === 0) {
+  if (eligible.length === 0 && requires && scoped.length > 0) {
+    const listed = scoped.map((d) => {
+      const known = kinds.get(d) ?? listedRuntimeKind(d);
+      const kind = requires.runtimeKind ? `, ${known ?? "kind unknown"}` : "";
+      return `${deviceEntryId(d) ?? "?"} (${d.platform}${kind})`;
+    });
+    throw requirementsError(
+      `No booted device satisfies this e2e test's ${describeRequires(requires)}. Booted devices: ${listed.join(", ")}.`
+    );
+  }
+  if (eligible.length === 0) {
     const what = opts.platform ? `No booted ${opts.platform} device found.` : "No booted device found.";
     throw deviceResolutionError(
       `${what} Pass a device id or platform explicitly.${connectedIosDeviceHint(devices, opts.platform)}`,
@@ -171074,8 +171251,8 @@ async function resolveFlowDevice(registry2, ctx, opts) {
     );
   }
   throw deviceResolutionError(
-    `${scoped.length} booted devices matched \u2014 pass --device or --platform to disambiguate.`,
-    scoped
+    `${eligible.length} booted devices matched \u2014 pass --device or --platform to disambiguate.`,
+    eligible
   );
 }
 function stripDeviceKeys(args) {
@@ -178725,10 +178902,10 @@ var zodSchema71 = external_exports.object({
   ),
   e2e_test_path: external_exports.string().optional().describe("Absolute path to an e2e test .yaml on the client."),
   device: external_exports.string().optional().describe(
-    "Device id to run against (iOS UDID, Android/Vega serial, Chromium id), as list-devices reports it. Auto-detected when omitted, but only when exactly one booted device matches; with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up."
+    "Device id to run against (iOS UDID, Android/Vega serial, Chromium id), as list-devices reports it. Auto-detected when omitted, but only when exactly one booted device matches (optionally narrowed by `platform` and the e2e test's `requires:` block); with several booted the run fails and lists them, so pass this explicitly whenever more than one device is up."
   ),
   platform: external_exports.enum(SELECTABLE_PLATFORMS).optional().describe(
-    "Restrict auto-detection to this platform when several devices are booted. `ios` selects local simulators only; `ios-remote` selects a remote one. `chromium` with no `device` also makes the runner boot an Electron instance for a standalone e2e test from its `launch` step's chromium value and tear it down after the run, with no fallback to auto-detection (a single-key `launch: { chromium: \u2026 }` map does this on its own; a fragment, or a launch map without a `chromium` key, is still auto-detected). That value must be an Electron app path on the tool-server host: the bare-string `launch:` the recorder writes holds a bundle id, which fails the run with `Electron boot: path does not exist`, so first edit it to `{ chromium: <app path> }`."
+    "Restrict auto-detection to this platform when several devices are booted. `ios` selects local simulators only; `ios-remote` selects a remote one. `chromium` with no `device` also makes the runner boot an Electron instance for a standalone e2e test from its `launch` step's chromium value and tear it down after the run, with no fallback to auto-detection (a single-key `launch: { chromium: \u2026 }` map, or a `requires:` block that allows only chromium, does this on its own; a fragment, or a launch map without a `chromium` key, is still auto-detected). That value must be an Electron app path on the tool-server host: the bare-string `launch:` the recorder writes holds a bundle id, which fails the run with `Electron boot: path does not exist`, so first edit it to `{ chromium: <app path> }`."
   ),
   updateBaselines: external_exports.boolean().optional().describe(
     "Write/refresh screenshot baselines for `snapshot` steps instead of diffing against them, also in the e2e tests that tool: e2e-execute steps run, unless such a step sets updateBaselines itself. Over a link, the client writes the new baselines when the run ends."
@@ -178839,7 +179016,17 @@ Without a link, every step kind runs.`,
           );
         }
       }
+      if (params.device) {
+        await assertDeviceMeetsRequires(resolveDevice(params.device), flow.requires);
+      } else if (params.platform) {
+        assertPlatformMeetsRequires(
+          params.platform,
+          flow.requires,
+          `the ${params.platform} target this run was pointed at`
+        );
+      }
       if (flow.executionPrerequisite && !params.prerequisiteAcknowledged) {
+        await resolveRunDevice(registry2, ctx, flow, params, flowsDir, seed, viaUpload, project);
         return {
           e2eTest: flowName,
           flow: flowName,
@@ -178939,8 +179126,15 @@ Without a link, every step kind runs.`,
 async function resolveRunDevice(registry2, ctx, flow, params, flowDir, runStack, viaUpload, project) {
   if (!params.device) {
     const leading = await leadingLaunch(flow, runStack, { registry: registry2, project });
-    const spec = leading && chromiumBootSpec(leading.app, params.platform);
+    const chromiumOnly = flow.requires?.platform?.length === 1 && flow.requires.platform[0] === "chromium";
+    const platform = params.platform ?? (chromiumOnly ? "chromium" : void 0);
+    const spec = leading && chromiumBootSpec(leading.app, platform);
     if (spec) {
+      assertPlatformMeetsRequires(
+        "chromium",
+        flow.requires,
+        "the chromium app its leading launch boots"
+      );
       let booted;
       try {
         booted = await bootChromiumForFlow(spec, flowDir, viaUpload);
@@ -178953,16 +179147,25 @@ async function resolveRunDevice(registry2, ctx, flow, params, flowDir, runStack,
       if (!flowScopesDevice(registry2, flow.steps)) return { device: null, booted: null };
       try {
         return {
-          device: await resolveFlowDevice(registry2, ctx, resolveOpts(params)),
+          device: await resolveFlowDevice(registry2, ctx, {
+            ...resolveOpts(params),
+            requires: flow.requires
+          }),
           booted: null
         };
       } catch (err) {
-        if (getFailureSignal(err)?.error_code !== FAILURE_CODES.FLOW_DEVICE_RESOLUTION) throw err;
+        const signal = getFailureSignal(err);
+        if (signal?.error_code !== FAILURE_CODES.FLOW_DEVICE_RESOLUTION || signal.failure_stage === "flow_requirements") {
+          throw err;
+        }
         return { device: null, booted: null };
       }
     }
   }
-  const device = await resolveFlowDevice(registry2, ctx, resolveOpts(params));
+  const device = await resolveFlowDevice(registry2, ctx, {
+    ...resolveOpts(params),
+    requires: flow.requires
+  });
   return { device, booted: null };
 }
 function resolveOpts(params) {
@@ -179368,6 +179571,13 @@ async function execRunStep(state3, step, scope) {
   }
   const refusal = fragmentLoadRefusal(state3.registry, fragment, target);
   if (refusal !== void 0) return fail(refusal);
+  if (state3.device) {
+    try {
+      await assertDeviceMeetsRequires(state3.device, fragment.requires, `Fragment "${target}"`);
+    } catch (err) {
+      return fail(errMsg4(err));
+    }
+  }
   pushReport(state3, {
     index,
     kind: "run",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.32.1-next.2",
+  "version": "0.32.1-next.4",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-create-e2e/references/e2e-yaml.md

@@ -42,6 +42,8 @@ E2E tests never store a device id. The runner binds the device. `launch:` restar
 
 The one exception is a device _scope_ rather than a target: `stop-all-simulator-servers`' `devices` list **is** kept in the YAML, because without it the step means the machine-wide sweep and would tear down devices other agents are mid-session on. Replay rebinds a recorded scope only when you pass `device` explicitly: an auto-detected device would retarget the teardown at a device the test never named. So the recorded ids are what run when you replay without `device`; on another host they reap nothing and come back in `unmatched`, so re-record the cleanup test there or pass `device`. A step that recorded no scope is narrowed onto the run's device **only when the run resolved one**. A cleanup test whose only step is that teardown needs no device, so with none or several booted it resolves none, replays as the machine-wide sweep, and still reports a pass. Record the scope, or pass `device` at replay, whenever the sweep must stay confined.
 
+A top-level `requires:` block limits the targets a test runs on: `platform` (`ios`, `android`, `chromium`, `vega`, or a list; `ios` covers a remote simulator) and `runtimeKind` (`tv` or `mobile`). Add it for a platform-specific or TV-specific scenario. A directory run skips a test whose target does not match; a `run:` fragment that does not match fails its step.
+
 ## Selectors
 
 Use values that meet the [stable-selector definition](../SKILL.md#stable-selectors). Always write explicit maps: