@debugswift/ios-simulator-cli 1.6.0 → 1.7.0

package/README.md

@@ -10,14 +10,17 @@ A command-line tool for interacting with iOS simulators. Control UI, capture scr
 
 ### Homebrew (recommended)
 
+The formula lives in this repo, so tap it explicitly (Homebrew otherwise looks for a separate `homebrew-ios-simulator-cli` repo that does not exist):
+
 ```bash
-brew install DebugSwift/ios-simulator-cli/ios-simulator-cli
+brew tap DebugSwift/ios-simulator-cli https://github.com/DebugSwift/ios-simulator-cli
+brew install ios-simulator-cli
 ```
 
 To install the latest from `main`:
 
 ```bash
-brew install --HEAD DebugSwift/ios-simulator-cli/ios-simulator-cli
+brew install --HEAD ios-simulator-cli
 ```
 
 ### npm

package/build/index.js

@@ -62,8 +62,46 @@ function getIdbPath() {
         }
         return expandedPath;
     }
+    const pythonBins = [];
+    const pythonRoot = path_1.default.join(os_1.default.homedir(), "Library/Python");
+    if (fs_1.default.existsSync(pythonRoot)) {
+        for (const entry of fs_1.default.readdirSync(pythonRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            pythonBins.push(path_1.default.join(pythonRoot, entry.name, "bin/idb"));
+        }
+    }
+    const candidates = preferWorkingIdb([
+        path_1.default.join(os_1.default.homedir(), ".local/bin/idb"),
+        ...pythonBins,
+        "/opt/homebrew/bin/idb",
+        "/usr/local/bin/idb",
+    ].filter((candidate) => fs_1.default.existsSync(candidate)));
+    if (candidates.length > 0) {
+        return candidates[0];
+    }
     return "idb";
 }
+/** Prefer arm64-friendly idb installs (Xcode/system Python) over Intel Homebrew Python. */
+function preferWorkingIdb(candidates) {
+    const score = (idbPath) => {
+        try {
+            const shebang = fs_1.default.readFileSync(idbPath, "utf8").split("\n", 1)[0] ?? "";
+            if (shebang.includes("/usr/local/opt/python"))
+                return 2;
+            if (shebang.includes("Xcode.app") ||
+                shebang.includes("/usr/bin/python") ||
+                shebang.includes("/opt/homebrew/")) {
+                return 0;
+            }
+            return 1;
+        }
+        catch {
+            return 1;
+        }
+    };
+    return [...candidates].sort((a, b) => score(a) - score(b));
+}
 async function idb(...args) {
     return run(getIdbPath(), args);
 }
@@ -145,6 +183,61 @@ function parseEnvPairs(values) {
     }
     return env;
 }
+function matchesSearch(value, term, mode, sensitive) {
+    if (value == null)
+        return false;
+    const v = sensitive ? value : value.toLowerCase();
+    const t = sensitive ? term : term.toLowerCase();
+    return mode === "exact" ? v === t : v.includes(t);
+}
+function findUiElements(elements, options) {
+    const results = [];
+    for (const element of elements) {
+        const label = element.AXLabel;
+        const uniqueId = element.AXUniqueId;
+        const elementType = element.type;
+        const matchesAnySearch = options.search.some((term) => matchesSearch(label, term, options.matchMode, options.caseSensitive) ||
+            matchesSearch(uniqueId, term, options.matchMode, options.caseSensitive));
+        const matchesType = options.type == null ||
+            (elementType != null &&
+                elementType.toLowerCase() === options.type.toLowerCase());
+        if (matchesAnySearch && matchesType) {
+            results.push(element);
+        }
+        const children = element.children;
+        if (children && children.length > 0) {
+            results.push(...findUiElements(children, options));
+        }
+    }
+    return results;
+}
+async function fetchUiTree(udid) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(udid));
+    const { stdout } = await idb("ui", "describe-all", "--udid", actualUdid, "--json", "--nested");
+    return JSON.parse(stdout);
+}
+function elementCenter(element) {
+    const frame = element.frame;
+    if (!frame ||
+        typeof frame.x !== "number" ||
+        typeof frame.y !== "number" ||
+        typeof frame.width !== "number" ||
+        typeof frame.height !== "number") {
+        throw new Error("Element has no valid frame for tapping");
+    }
+    return {
+        x: Math.round(frame.x + frame.width / 2),
+        y: Math.round(frame.y + frame.height / 2),
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const matchModeSchema = zod_1.z.enum(["substring", "exact"]);
+const workflowSchema = zod_1.z.object({
+    udid: udidSchema,
+    steps: zod_1.z.array(zod_1.z.record(zod_1.z.unknown())).min(1),
+});
 async function cmdGetBootedSimId() {
     const { id, name } = await getBootedDevice();
     console.log(`Booted Simulator: "${name}". UUID: "${id}"`);
@@ -188,38 +281,8 @@ async function cmdUiDescribePoint(options) {
     console.log(stdout);
 }
 async function cmdUiFindElement(options) {
-    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
-    const { stdout } = await idb("ui", "describe-all", "--udid", actualUdid, "--json", "--nested");
-    const uiData = JSON.parse(stdout);
-    function matchesSearch(value, term, mode, sensitive) {
-        if (value == null)
-            return false;
-        const v = sensitive ? value : value.toLowerCase();
-        const t = sensitive ? term : term.toLowerCase();
-        return mode === "exact" ? v === t : v.includes(t);
-    }
-    function findElements(elements) {
-        const results = [];
-        for (const element of elements) {
-            const label = element.AXLabel;
-            const uniqueId = element.AXUniqueId;
-            const elementType = element.type;
-            const matchesAnySearch = options.search.some((term) => matchesSearch(label, term, options.matchMode, options.caseSensitive) ||
-                matchesSearch(uniqueId, term, options.matchMode, options.caseSensitive));
-            const matchesType = options.type == null ||
-                (elementType != null &&
-                    elementType.toLowerCase() === options.type.toLowerCase());
-            if (matchesAnySearch && matchesType) {
-                results.push(element);
-            }
-            const children = element.children;
-            if (children && children.length > 0) {
-                results.push(...findElements(children));
-            }
-        }
-        return results;
-    }
-    console.log(JSON.stringify(findElements(uiData)));
+    const uiData = await fetchUiTree(options.udid);
+    console.log(JSON.stringify(findUiElements(uiData, options)));
 }
 async function cmdUiView(options) {
     const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
@@ -383,6 +446,240 @@ async function cmdLaunchApp(options) {
         ? `App ${options.bundleId} launched successfully with PID: ${pid}`
         : `App ${options.bundleId} launched successfully`);
 }
+function stepUdid(globalUdid, step) {
+    const value = step.udid;
+    if (value == null)
+        return globalUdid;
+    return udidSchema.parse(value);
+}
+function parseStepObject(step, index) {
+    if (typeof step !== "object" || step == null || Array.isArray(step)) {
+        throw new Error(`Step ${index + 1}: expected an object`);
+    }
+    const keys = Object.keys(step);
+    if (keys.length !== 1) {
+        throw new Error(`Step ${index + 1}: expected exactly one action, got: ${keys.join(", ") || "(empty)"}`);
+    }
+    return step;
+}
+async function runWorkflowStep(action, payload, globalUdid, index) {
+    const stepLabel = `Step ${index + 1}: ${action}`;
+    console.log(stepLabel);
+    switch (action) {
+        case "wait": {
+            const ms = zod_1.z.number().int().nonnegative().parse(payload);
+            await sleep(ms);
+            return;
+        }
+        case "open": {
+            if (payload != null && payload !== true) {
+                throw new Error(`${stepLabel} expects true or no value`);
+            }
+            await cmdOpenSimulator();
+            return;
+        }
+        case "launch-app": {
+            const step = zod_1.z
+                .object({
+                bundleId: zod_1.z.string().min(1),
+                terminateRunning: zod_1.z.boolean().optional(),
+                env: zod_1.z.record(zod_1.z.string()).optional(),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdLaunchApp({
+                udid: stepUdid(globalUdid, step),
+                bundleId: step.bundleId,
+                terminateRunning: step.terminateRunning,
+                env: step.env,
+            });
+            return;
+        }
+        case "install-app": {
+            const step = zod_1.z
+                .object({
+                appPath: zod_1.z.string().min(1),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdInstallApp(step.appPath, stepUdid(globalUdid, step));
+            return;
+        }
+        case "tap": {
+            const step = zod_1.z
+                .object({
+                x: zod_1.z.number().optional(),
+                y: zod_1.z.number().optional(),
+                search: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
+                type: zod_1.z.string().optional(),
+                matchMode: matchModeSchema.optional(),
+                caseSensitive: zod_1.z.boolean().optional(),
+                index: zod_1.z.number().int().nonnegative().optional(),
+                duration: zod_1.z.string().regex(/^\d+(\.\d+)?$/).optional(),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            const udid = stepUdid(globalUdid, step);
+            if (step.x != null && step.y != null) {
+                await cmdUiTap({
+                    udid,
+                    x: step.x,
+                    y: step.y,
+                    duration: step.duration,
+                });
+                return;
+            }
+            if (step.search == null) {
+                throw new Error(`${stepLabel} requires x/y or search`);
+            }
+            const search = Array.isArray(step.search) ? step.search : [step.search];
+            const matches = findUiElements(await fetchUiTree(udid), {
+                search,
+                type: step.type,
+                matchMode: step.matchMode ?? "substring",
+                caseSensitive: step.caseSensitive ?? false,
+            });
+            const matchIndex = step.index ?? 0;
+            if (matches.length === 0) {
+                throw new Error(`${stepLabel} found no element matching: ${search.join(", ")}`);
+            }
+            if (matchIndex >= matches.length) {
+                throw new Error(`${stepLabel} index ${matchIndex} out of range (${matches.length} matches)`);
+            }
+            const { x, y } = elementCenter(matches[matchIndex]);
+            await cmdUiTap({ udid, x, y, duration: step.duration });
+            return;
+        }
+        case "type": {
+            const step = zod_1.z
+                .object({
+                text: zod_1.z.string().min(1).max(500).regex(/^[\x20-\x7E]+$/),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdUiType(step.text, stepUdid(globalUdid, step));
+            return;
+        }
+        case "swipe": {
+            const step = zod_1.z
+                .object({
+                xStart: zod_1.z.number(),
+                yStart: zod_1.z.number(),
+                xEnd: zod_1.z.number(),
+                yEnd: zod_1.z.number(),
+                duration: zod_1.z.string().regex(/^\d+(\.\d+)?$/).optional(),
+                delta: zod_1.z.number().optional(),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdUiSwipe({
+                udid: stepUdid(globalUdid, step),
+                xStart: step.xStart,
+                yStart: step.yStart,
+                xEnd: step.xEnd,
+                yEnd: step.yEnd,
+                duration: step.duration,
+                delta: step.delta,
+            });
+            return;
+        }
+        case "screenshot": {
+            const step = zod_1.z
+                .object({
+                output: zod_1.z.string().min(1),
+                type: zod_1.z.enum(["png", "tiff", "bmp", "gif", "jpeg"]).optional(),
+                display: zod_1.z.enum(["internal", "external"]).optional(),
+                mask: zod_1.z.enum(["ignored", "alpha", "black"]).optional(),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdScreenshot({
+                udid: stepUdid(globalUdid, step),
+                outputPath: step.output,
+                type: step.type,
+                display: step.display,
+                mask: step.mask,
+            });
+            return;
+        }
+        case "ui-view": {
+            const step = zod_1.z
+                .object({
+                output: zod_1.z.string().optional(),
+                udid: udidSchema,
+            })
+                .parse(payload);
+            await cmdUiView({
+                udid: stepUdid(globalUdid, step),
+                output: step.output,
+            });
+            return;
+        }
+        default:
+            throw new Error(`${stepLabel} uses unknown action "${action}". Run ios-simulator-cli run --help for supported actions.`);
+    }
+}
+async function cmdRun(configPath) {
+    const absolutePath = path_1.default.isAbsolute(configPath)
+        ? configPath
+        : path_1.default.resolve(configPath);
+    if (!fs_1.default.existsSync(absolutePath)) {
+        throw new Error(`Config file not found: ${absolutePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(absolutePath, "utf8"));
+    }
+    catch {
+        throw new Error(`Invalid JSON in config file: ${absolutePath}`);
+    }
+    const workflow = workflowSchema.parse(parsed);
+    for (let i = 0; i < workflow.steps.length; i++) {
+        const step = parseStepObject(workflow.steps[i], i);
+        const [action, payload] = Object.entries(step)[0];
+        await runWorkflowStep(action, payload, workflow.udid, i);
+    }
+    console.log(`Completed ${workflow.steps.length} step(s)`);
+}
+function runHelpBody() {
+    return `Run a JSON workflow file against the booted simulator.
+
+Config format:
+{
+  "udid": "<optional-simulator-uuid>",
+  "steps": [
+    { "open": true },
+    { "wait": 1000 },
+    { "launch-app": { "bundleId": "com.example.app", "terminateRunning": true } },
+    { "tap": { "search": "Sign In", "type": "Button" } },
+    { "tap": { "x": 200, "y": 400 } },
+    { "type": { "text": "hello@world.com" } },
+    { "swipe": { "xStart": 200, "yStart": 600, "xEnd": 200, "yEnd": 200 } },
+    { "screenshot": { "output": "result.png" } }
+  ]
+}
+
+Supported step actions:
+  wait              Milliseconds to pause (number)
+  open              Open Simulator.app (true)
+  launch-app        Launch app by bundle ID
+  install-app       Install .app or .ipa
+  tap               Tap by x/y or by accessibility search label
+  type              Type ASCII text
+  swipe             Swipe gesture
+  screenshot        Save screenshot to file
+  ui-view           Capture compressed JPEG view
+
+Each step object must contain exactly one action key.
+Step payloads may include an optional "udid" to override the config-level udid.`;
+}
+function printRunHelp() {
+    console.log(`ios-simulator-cli run --config <path>
+  ios-simulator-cli --config <path>
+
+${runHelpBody()}
+`);
+}
 function printHelp() {
     console.log(`ios-simulator-cli v${VERSION}
 
@@ -406,6 +703,8 @@ Commands:
   stop-recording                        Stop an active simulator recording
   install-app --app-path <path> [--udid <uuid>]
   launch-app --bundle-id <id> [--terminate-running] [--env KEY=VALUE] [--udid <uuid>]
+  run --config <path>                    Run a JSON workflow file
+  --config <path>                        Shorthand for run --config
 
 Global options:
   -h, --help                            Show this help
@@ -420,6 +719,10 @@ Examples:
   ios-simulator-cli ui tap --x 200 --y 400
   ios-simulator-cli screenshot --output home.png
   ios-simulator-cli launch-app --bundle-id com.apple.mobilesafari
+  ios-simulator-cli run --config flow.json
+  ios-simulator-cli --config flow.json
+
+${runHelpBody()}
 `);
 }
 async function handleUiCommand(args) {
@@ -564,7 +867,15 @@ async function handleUiCommand(args) {
 }
 async function main() {
     const args = process.argv.slice(2);
-    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    if (args.length === 0) {
+        printHelp();
+        return;
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        if (args[0] === "run") {
+            printRunHelp();
+            return;
+        }
         printHelp();
         return;
     }
@@ -674,6 +985,34 @@ async function main() {
             });
             return;
         }
+        case "run": {
+            if (rest.includes("--help") || rest.includes("-h")) {
+                printRunHelp();
+                return;
+            }
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    config: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values.config) {
+                printRunHelp();
+                return;
+            }
+            await cmdRun(values.config);
+            return;
+        }
+        case "--config": {
+            const configPath = rest[0];
+            if (!configPath || configPath.startsWith("-")) {
+                printRunHelp();
+                return;
+            }
+            await cmdRun(configPath);
+            return;
+        }
         default:
             throw new Error(`Unknown command: ${command}. Run ios-simulator-cli --help for usage.`);
     }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "CLI for interacting with the iOS simulator",
   "bin": {
     "ios-simulator-cli": "build/index.js"