@loadmill/droid-cua 2.43.0 → 2.44.0

package/README.md

@@ -69,10 +69,10 @@ You can also keep project run history in a results folder and review past runs f
 <h2 id="platforms">📱 Platforms</h2>
 
 - **Android** - Physical devices and emulators
-- **iOS** - Simulators on macOS
+- **iOS** - Simulators on macOS, and iPhones connected to your Mac by USB
 
 Desktop app support:
-- macOS: Android and iOS simulator workflows
+- macOS: Android, iOS simulator, and iPhone (USB) workflows
 - Windows: Android workflows only
 
 ## Requirements
@@ -90,6 +90,8 @@ Desktop app support:
 - Appium
 - XCUITest driver
 
+**iPhone over USB (macOS only):** see [Testing on a real iPhone](#testing-on-a-real-iphone).
+
 ---
 
 <h2 id="features">✨ Features</h2>
@@ -97,7 +99,7 @@ Desktop app support:
 - **Desktop-first workflow** - Create, run, and manage tests from one app
 - **Setup guidance** - Configure API access and platform prerequisites in the app
 - **Device and simulator connection** - Connect Android targets and iOS simulators
-- **Network certificate preparation** - Manage one active root CA and install it on a connected local simulator or supported emulator from the desktop app's Tools menu
+- **Network certificate preparation** - Manage one active root CA and install it on a connected local simulator or supported emulator, or get manual setup steps for a physical iPhone or Android phone, from the desktop app's Tools menu
 - **Natural-language test creation** - Describe flows in plain English
 - **Test management** - Create, edit, save, and rerun reusable scripts, including tests organized in nested project folders
 - **Live execution logs** - Watch actions and progress as tests run
@@ -106,15 +108,19 @@ Desktop app support:
 - **Run video export** - Generate and download a polished MP4 replay from a desktop run's screenshots and instruction timeline
 - **Headless support** - Reuse scripts in CLI and automation workflows
 
-**Network certificate preparation:** Use **Tools → Manage Certificates** to see the active CA, upload a single `.pem` containing a CA certificate and its matching unencrypted private key, generate a new Droid CA, or remove the active CA. Droid stores one active pair in `~/.droid-cua/network/`; upload copies the PEM material without changing the source file, and removal does not change device trust. Connect a local iOS Simulator or a rootable Android Emulator, then choose **Tools → Install Network Certificate**. This installs the active CA, generating a Droid CA if none exists. Devices prepared with a previous CA may need installation again. Droid may reapply Android system trust when a prepared emulator reconnects after a cold boot. Restart an already running Android app after installation so it loads the updated trust store. Android certificate setup supports capable rootable images through Android 16; Google Play images without root access and Android 17 are not supported.
+**Network certificate preparation:** Use **Tools → Manage Certificates** to see the active CA, upload a single `.pem` containing a CA certificate and its matching unencrypted private key, generate a new Droid CA, or remove the active CA. Droid stores one active pair in `~/.droid-cua/network/`; upload copies the PEM material without changing the source file, and removal does not change device trust. Connect a local iOS Simulator or a rootable Android Emulator, then choose **Tools → Install Network Certificate**. This installs the active CA, generating a Droid CA if none exists. Devices prepared with a previous CA may need installation again. Droid may reapply Android system trust when a prepared emulator reconnects after a cold boot. Restart an already running Android app after installation so it loads the updated trust store. With a local iPhone connected by USB, **Tools → Install Network Certificate** does not change the phone; it shows the manual steps instead. **Send to iPhone** opens the macOS share menu with a DER `.cer` copy of the active CA named after its common name (for example `Droid CUA Root fbd877ab.cer`, written to `~/.droid-cua/network/iphone/`); choose AirDrop and your iPhone, install it from **Settings → Profile Downloaded**, then turn on full trust for that common name under **Settings → General → About → Certificate Trust Settings**. Android Emulator certificate setup supports capable rootable images through Android 16; Google Play images without root access and Android 17 are not supported. With a physical Android phone connected over ADB, **Tools → Install Network Certificate** writes a PEM `.crt` copy of the active CA named after its common name (for example `Droid CUA Root fbd877ab.crt`, in `~/.droid-cua/network/android/`), copies it to the phone's `/sdcard/Download/` folder with `adb push`, and shows the manual steps; it changes no phone settings. Install it from **Settings → Security → Encryption & credentials → Install a certificate → CA certificate** (names vary by vendor), then restart the tested app. If the copy fails, Droid shows the local file path so you can copy it to the phone yourself.
 
 **Network capture:** Enable **Network Capture** in desktop Settings or pass `--capture-network` for CLI tests. Local Chrome and Edge capture through Playwright with no certificate or proxy setup, using the same network queries and report cards as mobile. Capture covers the test browser context, including frames and popups, from run start. Previously loaded traffic is not recovered and existing pages are not automatically reloaded. CLI `--url` navigation happens after capture starts. Cloud browser capture, WebSocket messages and HAR export are not supported.
 
 **Mobile setup:** Manually route a prepared local simulator or emulator to `127.0.0.1:8765` (`10.0.2.2:8765` from Android Emulator). Enable **Network Capture** in desktop Settings to keep the proxy forwarding while Droid is open and automatically capture every local mobile test, including each project or scenario case. Existing **Network Proxy** settings do not turn capture on; opt in to the new setting. For CLI tests, pass `--capture-network`; this starts the proxy and writes one JSONL log per test. `--network-proxy` remains a forwarding-only CLI flag. Droid prints or logs each capture path and a best-effort health summary. Desktop artifacts are in the project's results folder; CLI artifacts are beside `--report` output when enabled, or under `logs/`. A missing CA stops mobile capture before test actions. No observed traffic or failed HTTPS decryption is reported separately from test assertions, but capture health does not prove that all traffic was observed. WebSocket messages are unsupported. Manual proxy setup is the V1 workflow. Droid does not change device or Mac proxy settings; turn off manually configured routing when finished. If Droid exits while routing remains enabled, restart Droid or clear the proxy to restore connectivity.
 
+**Physical iPhone capture:** A USB-connected iPhone reaches the proxy over Wi-Fi, so Droid listens on all Mac network interfaces (`0.0.0.0:8765`) instead of `127.0.0.1` while an iPhone is the target: in the CLI when `--avd ios-device:<udid|auto>` is used with `--capture-network` or `--network-proxy`, and in the desktop app while Network Capture is on and a local iPhone is connected (the proxy switches back to `127.0.0.1` on disconnect, but not during a run). Droid prints the setting to use, for example `On the iPhone, set Wi-Fi → Configure Proxy → Manual: server 192.168.1.23, port 8765.` Put the Mac and iPhone on the same Wi-Fi network with device-to-device traffic allowed, install and fully trust the Droid CA manually as described above, and set the iPhone proxy by hand; Droid never changes iPhone settings. Turn the iPhone proxy off after testing. Anyone on the same network can use the proxy while it listens on `0.0.0.0`, so use a trusted network. Apps that pin certificates still connect through the proxy, but their HTTPS is not decrypted.
+
+**Physical Android phone capture:** A phone connected over ADB (any serial other than `emulator-<port>`) is handled the same way as a physical iPhone: Droid listens on `0.0.0.0:8765`, in the CLI once the connected device turns out to be a phone (with `--capture-network` or `--network-proxy`) and in the desktop app while Network Capture is on and the phone is connected. Droid prints the setting to use, for example `On the Android phone, set Wi-Fi → Edit network → Proxy → Manual: hostname 192.168.1.23, port 8765.` Install the CA as a user certificate as described above and set the phone's Wi-Fi proxy by hand; Droid does not root the phone or change its settings, and turn the proxy off after testing. Since Android 7, apps trust user-installed CAs only when their network security config allows it, for example `<certificates src="user"/>` in `network_security_config.xml` or a `<debug-overrides>` block in a debuggable build. Debug and QA builds usually opt in; Play Store builds usually do not, so their HTTPS is not decrypted. Chrome trusts user CAs. Rooted-device system trust is not supported.
+
 Captures stop recording at 100 MiB per run, retaining a partial JSONL with a `CAPTURE_LIMIT` error. Traffic continues forwarding; live network queries report incomplete evidence. Captured bodies are limited to 1 MiB, both on the wire and after decompression. Compressed bodies that expand beyond that limit are omitted with `decoded-body-too-large`; this is incomplete evidence, not a missing response. The separate query evidence limit is 1,000,000 serialized characters. A capture limit or missing traffic is not proof that an application request never occurred.
 
-For troubleshooting, “No traffic observed” points to routing or an app that did not send traffic; it does not prove an expected request was absent. HTTPS connections with no decrypted requests point to certificate trust or interception compatibility. A port-in-use error means another Droid instance or proxy already owns the listener. Stop that listener before starting the CLI. A capture-size or write failure retains only partial evidence. iOS network validation is deferred; ordinary iOS runs without capture do not require proxy or certificate preparation.
+For troubleshooting, “No traffic observed” points to routing or an app that did not send traffic; it does not prove an expected request was absent. HTTPS connections with no decrypted requests point to certificate trust or interception compatibility. A port-in-use error means another Droid instance or proxy already owns the listener. Stop that listener before starting the CLI. A capture-size or write failure retains only partial evidence. Ordinary iOS runs without capture do not require proxy or certificate preparation.
 
 **Network questions and assertions:** With capture enabled, tests can ask Droid to inspect HTTP traffic and compare values across requests in natural language. For example: “Assert that the POST to `/pageview` after opening Home contains the `item_id` returned by `/home`.” The `query_network` tool searches by URL substring, method, status, flow IDs, request timestamps, or a starting step. It considers all matching exchanges in time order and sends only selected headers/bodies to one side call using the selected run model. Large results require a narrower search; they are not silently truncated. Optional observation windows wait the full duration, up to 30 seconds per query. Absence means only “no matching traffic observed during this window”; unavailable capture or insufficient evidence cannot establish absence. Desktop and HTML reports show one collapsed Network query card per call; expand it to see the question and answer. The agent receives structured flow references and capture diagnostics, while model details stay out of the timeline.
 
@@ -207,6 +213,10 @@ droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dc
 # Headless iOS simulator run
 droid-cua run tests/login.dcua --platform ios --avd "iPhone 16"
 
+# Check an iPhone connected by USB, then run on it
+droid-cua ios-device check --fix
+droid-cua run tests/login.dcua --avd ios-device:auto
+
 # List running desktop applications and their window IDs (macOS or Windows)
 droid-cua --target desktop --list-desktop-apps
 
@@ -287,7 +297,8 @@ droid-cua \
 ```
 
 Supported CLI options include:
-- `--avd`
+- `--avd` (including `ios-device:<udid>` or `ios-device:auto` for an iPhone connected by USB)
+- `--ios-team`
 - `--platform`
 - `--device-source`
 - `--device-name`
@@ -314,7 +325,7 @@ Supported CLI options include:
 - `--execution-prompt-file`
 - `--secrets`
 - `--record`
-- `--network-proxy` (local mobile sessions only; starts idle forwarding at `127.0.0.1:8765`)
+- `--network-proxy` (local mobile sessions only; starts idle forwarding at `127.0.0.1:8765`, or `0.0.0.0:8765` for `--avd ios-device:<udid|auto>` and physical Android phones)
 - `--capture-network` (local mobile and Chrome/Edge test runs; writes a JSONL log for each test, using a proxy only for mobile)
 - `--report`
 - `--report-metadata <path>`
@@ -375,6 +386,102 @@ HTML report (`--report`):
 droid-cua run tests/login.dcua --avd adb:emulator-5554 --report ./reports
 ```
 
+<h3 id="testing-on-a-real-iphone">Testing on a real iPhone</h3>
+
+The desktop app and the CLI can run tests on your own iPhone connected to your Mac by USB, on the
+apps already installed on it (TestFlight, App Store, or your team's builds).
+droid-cua installs a small helper app (WebDriverAgent) on the iPhone, signed
+with your company's Apple team; nothing is built from source at run time.
+
+Requirements:
+- macOS with an Xcode that supports the iPhone's iOS version, opened once.
+  Its first launch installs the device components and asks for a Mac admin password.
+- The iOS platform installed in that Xcode (**Xcode > Settings > Components**, or
+  `xcodebuild -downloadPlatform iOS`; about 10 GB). Xcode 26 doesn't include it.
+- Your Apple ID signed into Xcode (**Xcode > Settings > Apple Accounts**), as a
+  member of your company's **paid** Apple Developer team, with at least the
+  **Developer** role and **Access to Certificates, Identifiers & Profiles**.
+  Free Apple IDs are not supported.
+- The Appium XCUITest driver, as for Simulators.
+- On the iPhone, once: connect it by USB, unlock it and tap **Trust**; turn on
+  **Developer Mode** (**Settings > Privacy & Security > Developer Mode**, then let it
+  restart and confirm); set **Auto-Lock** to **Never** (**Settings > Display & Brightness**).
+- A test-only iPhone is recommended: droid-cua tests the apps and data already on
+  the phone and never resets it.
+
+Check the iPhone and set it up:
+
+```sh
+droid-cua ios-device check          # report each check and how to fix it
+droid-cua ios-device check --fix    # also set up signing and install the helper app
+```
+
+`ios-device check` prints every check as passed (`✔`), failed (`✖`), or a
+reminder (`!`), with the exact fix for each failure, and exits `0` only when the
+iPhone is ready. Use `--udid <udid>` to choose an iPhone (the first one connected
+by USB is used otherwise). The first `--fix` on a Mac runs a one-time Xcode signing
+build (about a minute); installing the helper app takes a few seconds. A test run
+performs the same checks and fixes automatically before it starts.
+
+**Xcode installed** names what's wrong: Xcode isn't in `/Applications`, the
+Command Line Tools are selected instead of Xcode (fix: `sudo xcode-select -s
+/Applications/Xcode.app`), or the Xcode license isn't accepted (fix: `sudo
+xcodebuild -license accept`). **iOS platform installed** checks that Xcode has the
+iOS platform for its iOS SDK, without which Xcode can't build for an iPhone (fix:
+install it from **Xcode > Settings > Components**, or run `xcodebuild
+-downloadPlatform iOS`, about 10 GB). **Apple team access** reads your teams from Xcode;
+on a fresh Mac, where Xcode hasn't saved them yet, droid-cua fetches them from
+Apple with a short Xcode build (a few seconds, at most once a minute). It then
+says whether no Apple account is signed into Xcode, or you're signed in but none
+of your accounts is in a paid Apple Developer team.
+
+Run tests on the iPhone:
+
+```sh
+droid-cua run tests/login.dcua --avd ios-device:auto
+droid-cua run tests/login.dcua --avd ios-device:00008120-001C18501A81A01E --ios-team ABCDE12345
+```
+
+- `--avd ios-device:<udid>` selects an iPhone; `ios-device:auto` picks the first
+  iPhone connected by USB. The platform is detected as iOS from the token.
+  Running `droid-cua` without `--avd` lists connected iPhones next to Simulators.
+- `--ios-team <TEAMID>` chooses the Apple team that signs the helper app when you
+  belong to several paid teams. `DROID_CUA_IOS_TEAM_ID` works too; the flag wins.
+- `--app` is not used for a local iPhone: tests run against apps already installed
+  on it, so open the app in your test instructions (for example, `Open the Settings app`).
+- After the iPhone restarts, unlock it. On the first run after a restart or a new
+  helper install, the iPhone may ask for your passcode to allow automation; enter
+  it and droid-cua continues. If the iPhone locks during a run, droid-cua pauses
+  until you unlock it.
+- After a major iOS update, droid-cua tells you which Xcode to install and open once.
+
+In the desktop app:
+
+- Run the Setup Wizard (**Help > Run Setup Wizard**) and choose **iPhone (USB)**.
+  The **Connect iPhone** checklist runs the same checks as `ios-device check`.
+  Steps you do on the iPhone or in Xcode (plug in, Trust, Developer Mode, unlock,
+  device components) re-check every few seconds and turn green on their own.
+  **Set up signing** and **Install helper app** run the fix and stream its progress.
+  When the Command Line Tools are selected or the Xcode license isn't accepted,
+  **Xcode installed** offers **Set Xcode Developer Path** or **Accept Xcode License**
+  (both ask for a Mac admin password). When the iOS platform is missing,
+  **iOS platform installed** offers **Download iOS Platform**, which runs
+  `xcodebuild -downloadPlatform iOS` (about 10 GB).
+  Auto-Lock and the dedicated test iPhone are shown as reminders and don't block.
+- If you belong to several paid Apple teams, choose the team in the wizard. The
+  desktop app remembers it and uses it for every iPhone run.
+- Connected iPhones appear in the iOS device picker next to Simulators, with a
+  hint when the iPhone isn't trusted yet or Developer Mode is off. droid tests the
+  apps already installed on the iPhone and never installs any.
+- The connection log and the run view highlight what needs you on the iPhone:
+  *Enter your passcode on the iPhone to allow automation*, *iPhone locked — unlock
+  to continue*, and *Your iPhone is on iOS N. Install Xcode N and open it once.*
+
+Known limits: USB only (no Wi-Fi), one iPhone at a time, attended runs (someone
+needs to unlock the phone and approve prompts), macOS only, and no `.ipa`
+installation. Verified on iOS 26; iOS 17 to 26 are expected to work. iOS betas
+and iOS 27 are not supported yet.
+
 LambdaTest CLI runs:
 - Use `--device-source lambdatest` with `--platform`, `--device-name`, `--os-version`, `--app`, and `--instructions`.
 - Set `LAMBDATEST_USERNAME` and `LAMBDATEST_ACCESS_KEY` in the environment.

package/build/index.js

@@ -19,7 +19,7 @@ import { resolveExecutionTestData } from "./src/core/test-data.js";
 import { getDefaultSecretsPath, resolveExecutionSecrets } from "./src/core/secrets.js";
 import { assertRuntimeCredentialsForProvider, createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
-import { artifactKindsForPool, resolveHeadlessTarget, scopeArtifactKindsToPool, shouldWaitForLoadmillCloudCompletion, } from "./src/cli/headless-target.js";
+import { artifactKindsForPool, resolveHeadlessTarget, resolveIosTeamId, scopeArtifactKindsToPool, shouldWaitForLoadmillCloudCompletion, } from "./src/cli/headless-target.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 import { clearLoadmillReportMetadata } from "./src/cli/loadmill-report-metadata.js";
@@ -38,6 +38,7 @@ import { droidReportUploadManager } from "./src/integrations/loadmill/report-upl
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 import { setCloudProgressListener } from "./src/device/cloud/progress.js";
 import { runSkillCommand } from "./src/cli/skill-command.js";
+import { runIosDeviceCommand } from "./src/cli/ios-device-command.js";
 import { formatLoadmillCloudNotEntitledMessage, isLoadmillCloudNotEntitledError, isLoadmillCloudUsageLimitError, } from "./src/device/cloud/loadmill-cloud/errors.js";
 import { fetchAndDownloadArtifacts, loadmillCloudAdapter } from "./src/device/cloud/loadmill-cloud/adapter.js";
 import { resolveRunPool } from "./src/device/cloud/loadmill-cloud/run-pool.js";
@@ -46,10 +47,26 @@ import { formatDuration } from "./src/core/report/run-log-model.js";
 import { createBrowserSessionTeardown, withLoadmillCloudSession } from "./src/cli/loadmill-cloud-session.js";
 import { createDesktopController, listDesktopApplications } from "./src/desktop/computer-use.js";
 import { createRunNetworkCapture } from "./src/network/run-network-capture.js";
+import { cliNetworkCaptureDeviceKind, cliNetworkProxyTarget } from "./src/cli/network-capture-device.js";
 import { loadCertificateAuthority } from "./src/network/certificate-authority.js";
 import { ensureCliAndroidCertificate, inspectNetworkDevice } from "./src/network/certificate-install.js";
 dotenv.config();
 let networkCapture = null;
+let cliNetworkProxyHost = null;
+async function startCliNetworkProxy(deviceName) {
+    const { host, instruction } = cliNetworkProxyTarget(deviceName);
+    if (host === cliNetworkProxyHost)
+        return;
+    try {
+        await networkCapture.startProxy({ host });
+    }
+    catch (error) {
+        throw new Error(`Droid network proxy could not start: ${error.message}`, { cause: error });
+    }
+    cliNetworkProxyHost = host;
+    if (instruction)
+        console.log(instruction);
+}
 process.once("SIGTERM", async () => {
     process.exitCode = 143;
     await networkCapture?.shutdown().catch(() => { });
@@ -78,12 +95,23 @@ if (args._[0] === "skill") {
         process.exit(1);
     }
 }
+if (args._[0] === "ios-device") {
+    try {
+        process.exit(await runIosDeviceCommand({ args }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\niOS device command failed: ${message}`);
+        process.exit(1);
+    }
+}
 const reportMetadataPath = typeof args["report-metadata"] === "string"
     && args["report-metadata"].trim().length > 0
     ? args["report-metadata"].trim()
     : null;
 await clearLoadmillReportMetadata(reportMetadataPath);
 const targetConfig = resolveHeadlessTarget(args);
+const iosTeamId = resolveIosTeamId(args, targetConfig);
 let avdName = targetConfig.avdName;
 let platform = targetConfig.platform || null; // 'ios' or 'android'
 const recordScreenshots = args["record"] || false;
@@ -413,14 +441,8 @@ async function main() {
             process.exit(130);
         });
     }
-    if (networkCapture && !isBrowserTarget) {
-        try {
-            await networkCapture.startProxy();
-        }
-        catch (error) {
-            throw new Error(`Droid network proxy could not start: ${error.message}`, { cause: error });
-        }
-    }
+    if (networkCapture && !isBrowserTarget)
+        await startCliNetworkProxy(avdName);
     let preloadedHeadlessConfig = null;
     let preloadedHeadlessTarget = null;
     let headlessInstructionRuns = [];
@@ -463,6 +485,8 @@ async function main() {
         const selection = await selectDevice();
         platform = selection.platform;
         avdName = selection.deviceName;
+        if (networkCapture)
+            await startCliNetworkProxy(avdName);
     }
     let targetId;
     let deviceInfo;
@@ -801,18 +825,18 @@ async function main() {
         }
     }
     else {
-        targetId = await connectToDevice(avdName, platform);
+        targetId = await connectToDevice(avdName, platform, { teamId: iosTeamId });
+        const deviceKind = networkCapture ? cliNetworkCaptureDeviceKind(getConnectedDevicePlatform(), targetId) : null;
+        if (deviceKind === "android-device")
+            await startCliNetworkProxy(`adb:${targetId}`);
         if (captureNetwork) {
-            const connectedPlatform = getConnectedDevicePlatform();
-            if (connectedPlatform === "android") {
-                if (!/^emulator-\d+$/.test(targetId))
-                    throw new Error("--capture-network supports Android Emulators, not physical Android devices.");
+            if (deviceKind === "android-emulator") {
                 const ca = await loadCertificateAuthority();
                 const trust = await ensureCliAndroidCertificate(targetId, ca);
                 if (trust.changed)
                     console.log(`Reapplied Droid's network certificate on ${targetId}.`);
             }
-            else {
+            else if (deviceKind === "ios-simulator") {
                 await inspectNetworkDevice({ platform: "ios", deviceId: targetId });
             }
         }

package/build/src/cli/device-selector.js

@@ -5,6 +5,7 @@ import React, { useState } from 'react';
 import { render, Box, Text, useInput, useApp } from 'ink';
 import { exec } from "child_process";
 import { promisify } from "util";
+import { getConnectedIphones } from "./ios-device-list.js";
 const execAsync = promisify(exec);
 /**
  * Interactive selection component with arrow key navigation
@@ -171,16 +172,18 @@ async function getIOSDevices() {
  */
 export async function selectDevice() {
     // Check what's available
-    const [androidDevices, iosDevices] = await Promise.all([
+    const [androidDevices, iphones, simulators] = await Promise.all([
         getAndroidDevices(),
+        getConnectedIphones(),
         getIOSDevices(),
     ]);
+    const iosDevices = [...iphones, ...simulators];
     const hasAndroid = androidDevices.length > 0;
     const hasIOS = iosDevices.length > 0;
     if (!hasAndroid && !hasIOS) {
         console.error("\nNo devices found!");
         console.error("  Android: Connect a device or create an AVD, then run droid-cua again");
-        console.error("  iOS: Xcode Simulator must be available");
+        console.error("  iOS: Connect an iPhone by USB or make an Xcode Simulator available");
         process.exit(1);
     }
     // Build platform options
@@ -193,9 +196,13 @@ export async function selectDevice() {
         });
     }
     if (hasIOS) {
-        const runningCount = iosDevices.filter((d) => d.running).length;
+        const runningCount = simulators.filter((d) => d.running).length;
+        const counts = [
+            iphones.length > 0 ? `${iphones.length} iPhone(s)` : null,
+            simulators.length > 0 ? `${simulators.length} simulator(s)` : null,
+        ].filter(Boolean).join(", ");
         platformOptions.push({
-            label: `iOS${runningCount > 0 ? ` (${runningCount} running)` : ""} - ${iosDevices.length} simulator(s)`,
+            label: `iOS${runningCount > 0 ? ` (${runningCount} running)` : ""} - ${counts}`,
             value: "ios",
         });
     }
@@ -211,11 +218,11 @@ export async function selectDevice() {
     }
     // Select device
     const deviceList = platform === "ios" ? iosDevices : androidDevices;
-    const deviceType = platform === "ios" ? "Simulator" : "Android Target";
+    const deviceType = platform === "ios" ? (iphones.length > 0 ? "iOS Device" : "Simulator") : "Android Target";
     let deviceName;
     if (deviceList.length === 1) {
         deviceName = deviceList[0].value;
-        console.log(`Using ${deviceName} (only available ${deviceType.toLowerCase()})\n`);
+        console.log(`Using ${deviceList[0].label} (only available ${deviceType.toLowerCase()})\n`);
     }
     else {
         const selected = await renderSelection(`Select ${deviceType}`, deviceList);

package/build/src/cli/headless-target.js

@@ -1,4 +1,5 @@
 import { CLOUD_BROWSER_FAMILIES, CLOUD_BROWSER_VERSION_ALIASES, LOCAL_BROWSER_FAMILIES, } from "../browser/cloud-browser-catalog.js";
+import { parseIosDeviceToken } from "../device/ios/real-device/session.js";
 function normalizeTarget(value) {
     if (value == null || value === "") {
         return "mobile";
@@ -332,6 +333,9 @@ export function resolveHeadlessTarget(args = {}) {
     }
     if (deviceSource === "local") {
         assertNoCloudFlags(args);
+        if (platform === "android" && parseIosDeviceToken(avdName)) {
+            throw new Error("--avd ios-device:<udid> is an iPhone; use --platform ios or omit --platform.");
+        }
     }
     if (isCloudDeviceSource(deviceSource)) {
         const deviceName = hasNonEmptyString(args["device-name"]) ? args["device-name"].trim() : null;
@@ -393,3 +397,23 @@ export function resolveHeadlessTarget(args = {}) {
         listDevices: false,
     };
 }
+const APPLE_TEAM_ID_PATTERN = /^[A-Z0-9]{10}$/;
+export function normalizeIosTeamId(value) {
+    const teamId = readNonEmptyCliValue(value)?.toUpperCase() ?? null;
+    if (!teamId || !APPLE_TEAM_ID_PATTERN.test(teamId)) {
+        throw new Error("--ios-team must be a 10-character Apple team ID, for example ABCDE12345.");
+    }
+    return teamId;
+}
+export function resolveIosTeamId(args = {}, targetConfig = {}) {
+    if (args["ios-team"] == null) {
+        return null;
+    }
+    const teamId = normalizeIosTeamId(args["ios-team"]);
+    const isLocalMobile = targetConfig.target === "mobile" && targetConfig.deviceSource === "local";
+    const isOtherDevice = targetConfig.avdName != null && !parseIosDeviceToken(targetConfig.avdName);
+    if (!isLocalMobile || targetConfig.platform === "android" || isOtherDevice) {
+        throw new Error("--ios-team can only be used with a local iPhone (--avd ios-device:<udid> or ios-device:auto).");
+    }
+    return teamId;
+}

package/build/src/cli/ios-device-command.js

@@ -0,0 +1,121 @@
+import { runChecks as defaultRunChecks } from "../device/ios/real-device/readiness.js";
+import { IOS_DEVICE_PREFIX, parseIosDeviceToken } from "../device/ios/real-device/session.js";
+import { createStatusLine as defaultCreateStatusLine } from "./cloud-status-line.js";
+import { normalizeIosTeamId } from "./headless-target.js";
+const ALLOWED_OPTIONS = new Set(["_", "udid", "fix", "ios-team", "h", "help"]);
+const SYMBOLS = {
+    pass: { text: "✔", color: 32 },
+    fail: { text: "✖", color: 31 },
+    warn: { text: "!", color: 33 },
+    blocked: { text: "·", color: 90 },
+};
+export function iosDeviceCommandHelp() {
+    return [
+        "Usage: droid-cua ios-device check [options]",
+        "",
+        "Check that a real iPhone connected by USB is ready for droid-cua tests",
+        "",
+        "Options:",
+        "  --udid <udid>          Check this iPhone (default: the first iPhone connected by USB)",
+        "  --ios-team <TEAMID>    Apple team that signs the helper app (default: DROID_CUA_IOS_TEAM_ID, or your only paid team)",
+        "  --fix                  Set up signing and install the helper app (WebDriverAgent) when needed",
+        "  -h, --help             display help for command",
+        "",
+        "Examples:",
+        "  droid-cua ios-device check",
+        "  droid-cua ios-device check --udid 00008120-001C18501A81A01E --ios-team ABCDE12345 --fix",
+        "",
+        "Run tests on the iPhone with --avd ios-device:<udid> or --avd ios-device:auto.",
+    ].join("\n");
+}
+function parseIosDeviceCommandArgs(args, env) {
+    const unknownOption = Object.keys(args).find((key) => !ALLOWED_OPTIONS.has(key));
+    if (unknownOption)
+        throw new Error(`Unknown ios-device option --${unknownOption}.`);
+    if (args.help === true || args.h === true || args._.length === 1) {
+        return { help: iosDeviceCommandHelp() };
+    }
+    if (args._[1] !== "check" || args._.length !== 2) {
+        throw new Error(`Unknown ios-device command "${args._.slice(1).join(" ")}". Expected: droid-cua ios-device check`);
+    }
+    if (args.fix != null && typeof args.fix !== "boolean") {
+        throw new Error("--fix does not accept a value.");
+    }
+    let udid = null;
+    if (args.udid != null) {
+        const value = typeof args.udid === "string" ? args.udid.trim() : "";
+        if (!value)
+            throw new Error("--udid requires a value.");
+        udid = parseIosDeviceToken(value) ? parseIosDeviceToken(value).udid : value;
+    }
+    const teamValue = args["ios-team"] ?? env.DROID_CUA_IOS_TEAM_ID;
+    const teamId = teamValue == null || teamValue === "" ? null : normalizeIosTeamId(teamValue);
+    return { udid, teamId, fix: args.fix === true };
+}
+function paint(text, code, color) {
+    return color ? `\u001b[${code}m${text}\u001b[39m` : text;
+}
+function symbolFor(result, color) {
+    const symbol = SYMBOLS[result.blockedBy ? "blocked" : result.status];
+    return paint(symbol.text, symbol.color, color);
+}
+function guidanceLines(result, { fix }) {
+    if (result.blockedBy || result.status === "pass")
+        return [];
+    const lines = [];
+    if (result.details) {
+        lines.push(result.status === "fail" ? `Fix: ${result.details}` : result.details);
+    }
+    if (result.id === "apple_team" && result.status === "fail" && /paid Apple teams/.test(result.summary)) {
+        lines.push("Choose the team with --ios-team <TEAMID> (or set DROID_CUA_IOS_TEAM_ID).");
+    }
+    if (!fix && result.remediation?.some((step) => step.kind === "run_fix")) {
+        lines.push("Run droid-cua ios-device check --fix to do it now (a test run also does it automatically).");
+    }
+    return lines.map((line) => `    ${line}`);
+}
+export function formatReadinessReport({ ready, results, context }, { fix = false, color = false } = {}) {
+    const device = context?.device;
+    const heading = device
+        ? `iPhone readiness: ${device.name} (${device.model}, iOS ${device.iosVersion})`
+        : "iPhone readiness";
+    const lines = [heading, ""];
+    for (const result of results) {
+        lines.push(`${symbolFor(result, color)} ${result.title}: ${result.summary}`);
+        lines.push(...guidanceLines(result, { fix }));
+    }
+    lines.push("");
+    if (ready) {
+        lines.push(`Ready. Run tests on this iPhone with --avd ${IOS_DEVICE_PREFIX}${context.udid}`);
+    }
+    else {
+        lines.push("Not ready. Fix the first ✖ above, then run droid-cua ios-device check again.");
+    }
+    return lines;
+}
+function shouldUseColor() {
+    return Boolean(process.stdout.isTTY) && !Object.hasOwn(process.env, "NO_COLOR");
+}
+export async function runIosDeviceCommand({ args, env = process.env, output = console, runChecks = defaultRunChecks, createStatusLine = defaultCreateStatusLine, color = shouldUseColor(), } = {}) {
+    const command = parseIosDeviceCommandArgs(args ?? { _: ["ios-device"] }, env);
+    if (command.help) {
+        output.log(command.help);
+        return 0;
+    }
+    const statusLine = createStatusLine();
+    statusLine.start(command.fix ? "Checking and preparing the iPhone" : "Checking the iPhone");
+    let result;
+    try {
+        result = await runChecks({
+            udid: command.udid,
+            teamId: command.teamId,
+            autoFix: command.fix,
+            onProgress: (progress) => statusLine.update(progress.message),
+        });
+    }
+    finally {
+        statusLine.stop();
+    }
+    output.log(formatReadinessReport(result, { fix: command.fix, color }).join("\n"));
+    return result.ready ? 0 : 1;
+}

package/build/src/cli/ios-device-list.js

@@ -0,0 +1,32 @@
+import { listDevices } from "../device/ios/real-device/devicectl.js";
+import { IOS_DEVICE_PREFIX } from "../device/ios/real-device/session.js";
+export function iosDeviceStateHint(device) {
+    if (device.pairingState !== "paired")
+        return "not trusted";
+    if (device.developerModeStatus === "disabled")
+        return "Developer Mode off";
+    return null;
+}
+export function iosDeviceLabel(device) {
+    const details = [device.model, device.iosVersion ? `iOS ${device.iosVersion}` : null].filter(Boolean).join(" · ");
+    const hint = iosDeviceStateHint(device);
+    return `${device.name || device.udid} — ${details ? `${details} ` : ""}(USB)${hint ? ` — ${hint}` : ""}`;
+}
+export async function getConnectedIphones({ list = listDevices } = {}) {
+    let devices;
+    try {
+        devices = await list();
+    }
+    catch {
+        return [];
+    }
+    return devices
+        .filter((device) => device.transport === "wired" && device.udid)
+        .map((device) => ({
+        label: iosDeviceLabel(device),
+        value: `${IOS_DEVICE_PREFIX}${device.udid}`,
+        running: true,
+        realDevice: true,
+    }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+}

package/build/src/cli/network-capture-device.js

@@ -0,0 +1,21 @@
+import { parseIosDeviceToken } from "../device/ios/real-device/session.js";
+import { androidProxyInstruction, iphoneProxyInstruction, LAN_PROXY_HOST, macLanAddresses, NETWORK_PROXY_HOST } from "../network/local-proxy.js";
+function isAndroidEmulatorSerial(serial) {
+    return /^emulator-\d+$/.test(serial || "");
+}
+function physicalAndroidSerial(deviceName) {
+    const serial = typeof deviceName === "string" && deviceName.startsWith("adb:") ? deviceName.slice(4) : null;
+    return serial && !isAndroidEmulatorSerial(serial) ? serial : null;
+}
+export function cliNetworkProxyTarget(deviceName, addresses = macLanAddresses()) {
+    if (parseIosDeviceToken(deviceName))
+        return { host: LAN_PROXY_HOST, instruction: iphoneProxyInstruction(addresses) };
+    if (physicalAndroidSerial(deviceName))
+        return { host: LAN_PROXY_HOST, instruction: androidProxyInstruction(addresses) };
+    return { host: NETWORK_PROXY_HOST, instruction: null };
+}
+export function cliNetworkCaptureDeviceKind(platform, targetId) {
+    if (platform === "android")
+        return isAndroidEmulatorSerial(targetId) ? "android-emulator" : "android-device";
+    return parseIosDeviceToken(targetId) ? "iphone" : "ios-simulator";
+}