feat: Allow iOS device lookup by UUID

.nx/version-plans/version-plan-1778481764162.md

@@ -0,0 +1,5 @@
+---
+__default__: patch
+---
+
+Harness now lets you target connected physical iOS devices by hardware UDID as well as by device name or CoreDevice identifier, which makes it easier to select the exact device when multiple phones share similar names.

packages/platform-ios/README.md

@@ -68,13 +68,15 @@ Creates an iOS simulator device configuration.
 - `deviceName` - Name of the iOS simulator (e.g., 'iPhone 16 Pro Max')
 - `osVersion` - iOS version (e.g., '18.0')
 
-### `applePhysicalDevice(deviceName)`
+### `applePhysicalDevice(deviceNameOrId)`
 
 Creates a physical Apple device configuration.
 
 **Parameters:**
 
-- `deviceName` - Name of the physical device (e.g., 'iPhone (Your Name)')
+- `deviceNameOrId` - Name, CoreDevice identifier, or hardware UDID of the
+  physical device (e.g., 'iPhone (Your Name)' or
+  '6954F636-D116-52FA-9D00-8298BBB63705')
 
 ## Requirements
 

packages/platform-ios/src/__tests__/launch-options.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   getDeviceConnectionHost,
   getDeviceCtlLaunchArgs,
+  isMatchingDevice,
 } from '../xcrun/devicectl.js';
 import { getSimctlChildEnvironment } from '../xcrun/simctl.js';
 
@@ -62,4 +63,31 @@ describe('Apple app launch options', () => {
       })
     ).toBe('fd12:3456:789a::1');
   });
+
+  it('matches physical devices by name, CoreDevice identifier, or hardware UDID', () => {
+    const device = {
+      identifier: '6954F636-D116-52FA-9D00-8298BBB63705',
+      deviceProperties: {
+        name: 'G22RJQXC3V',
+        osVersionNumber: '26.0',
+      },
+      hardwareProperties: {
+        marketingName: 'iPhone',
+        productType: 'iPhone17,1',
+        udid: '00008140-001600222422201C',
+      },
+    };
+    const matchesName = isMatchingDevice(device, 'G22RJQXC3V');
+    const matchesIdentifier = isMatchingDevice(
+      device,
+      '6954F636-D116-52FA-9D00-8298BBB63705'
+    );
+    const matchesUdid = isMatchingDevice(device, '00008140-001600222422201C');
+    const matchesUnknownName = isMatchingDevice(device, 'Unknown iPhone');
+
+    expect(matchesName).toBe(true);
+    expect(matchesIdentifier).toBe(true);
+    expect(matchesUdid).toBe(true);
+    expect(matchesUnknownName).toBe(false);
+  });
 });

packages/platform-ios/src/xcrun/devicectl.ts

@@ -331,17 +331,32 @@ export const stopApp = async (
   ]);
 };
 
+export const isMatchingDevice = (
+  device: AppleDeviceInfo,
+  identifier: string
+): boolean => {
+  return (
+    device.deviceProperties.name === identifier ||
+    device.identifier === identifier ||
+    device.hardwareProperties.udid === identifier
+  );
+};
+
 export const getDevice = async (
-  name: string
+  identifier: string
 ): Promise<AppleDeviceInfo | null> => {
   const devices = await listDevices();
-  return (
-    devices.find((device) => device.deviceProperties.name === name) ?? null
-  );
+  const matchingDevice = devices.find((device) => {
+    return isMatchingDevice(device, identifier);
+  });
+
+  return matchingDevice ?? null;
 };
 
-export const getDeviceId = async (name: string): Promise<string | null> => {
-  const device = await getDevice(name);
+export const getDeviceId = async (
+  identifier: string
+): Promise<string | null> => {
+  const device = await getDevice(identifier);
   return device?.identifier ?? null;
 };
 

website/src/docs/platforms/ios.mdx

@@ -61,6 +61,7 @@ Xcode often installs multiple runtime versions (e.g., iOS 17.0 and iOS 18.0). Si
 ### Physical Devices
 
 To run on a connected physical iOS device, use the `applePhysicalDevice()` helper.
+You can identify the device by name, CoreDevice identifier, or hardware UDID.
 
 ```javascript
 applePlatform({